Local assets

Where to look up sources, where to download, and which commands to run for checkpoints, datasets, and repos.

Last updated: Oct 7, 2026

On this page

0. Prerequisites 1. Initialize directories and env vars 2. Where to look up required assets 3. Model checkpoints (inference)4. Benchmark datasets 5. local_assets manifest

0. Prerequisites

Use this page when a command says that a checkpoint, dataset, metric weight, generated output, or official result file is missing. WorldFoundry keeps these large or licensed files outside git; the repository holds code and manifests, while your machine or shared storage holds the assets those manifests reference.

Typical path: inspect the model or benchmark ID with worldfoundry-eval zoo ... --json, generate a per-benchmark asset plan when evaluating, then stage only what the next run needs. You do not need every benchmark asset before using the framework. For the unified conda env, see Environments.

Install the Hugging Face Hub package. The optional CLI (hf / huggingface-cli) is used when available; download scripts fall back to huggingface_hub.snapshot_download otherwise:

python -m pip install "huggingface_hub[cli]"

For gated models or datasets, accept upstream terms first, then export a token:

export HF_TOKEN="hf_..."   # or: huggingface-cli login

If huggingface.co is slow from your region, use the HF-Mirror hfd downloader (requires aria2c):

wget https://hf-mirror.com/hfd/hfd.sh
chmod a+x hfd.sh
export WORLDFOUNDRY_HF_ENDPOINT=https://hf-mirror.com
export HF_ENDPOINT="${WORLDFOUNDRY_HF_ENDPOINT}"

./hfd.sh Skywork/Matrix-Game-2.0 \
  --local-dir "${WORLDFOUNDRY_HFD_ROOT:-${HOME}/.cache/worldfoundry/models/checkpoints/hfd}/Skywork--Matrix-Game-2.0"

./hfd.sh BestWishYsh/ChronoMagic-Pro --dataset \
  --local-dir "${WORLDFOUNDRY_HFD_DATASET_ROOT:-${WORLDFOUNDRY_DATA_DIR:-${HOME}/.cache/worldfoundry/data}/datasets}/BestWishYsh__ChronoMagic-Pro"

Studio does not select a third-party mirror by default. Set WORLDFOUNDRY_HF_ENDPOINT to opt in for Studio child processes; direct Hugging Face tools read HF_ENDPOINT, as shown above. For gated repos, accept the license on huggingface.co first, then pass --hf_token "${HF_TOKEN}".

Mirrors are always opt-in. Studio-dispatched child processes inherit any HF_ENDPOINT exported by your shell and are not redirected to a third-party mirror by default. To override the endpoint only for WorldFoundry-managed children, export WORLDFOUNDRY_HF_ENDPOINT; it takes precedence over inherited HF_ENDPOINT.

1. Initialize directories and env vars

These directories are runtime state, not source code. Put them on durable storage with enough capacity for checkpoints, datasets, metric weights, generated videos, and result bundles.

export WORLDFOUNDRY_HOME="${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}"
export WORLDFOUNDRY_CACHE_DIR="${WORLDFOUNDRY_CACHE_DIR:-${WORLDFOUNDRY_HOME}/cache}"
export WORLDFOUNDRY_DATA_DIR="${WORLDFOUNDRY_DATA_DIR:-${WORLDFOUNDRY_CACHE_DIR}/data}"
export WORLDFOUNDRY_MODEL_DIR="${WORLDFOUNDRY_MODEL_DIR:-${WORLDFOUNDRY_CACHE_DIR}/models}"
export WORLDFOUNDRY_CKPT_DIR="${WORLDFOUNDRY_CKPT_DIR:-${WORLDFOUNDRY_MODEL_DIR}/checkpoints}"
export WORLDFOUNDRY_HFD_ROOT="${WORLDFOUNDRY_HFD_ROOT:-${WORLDFOUNDRY_CKPT_DIR}/hfd}"
export WORLDFOUNDRY_HFD_DATASET_ROOT="${WORLDFOUNDRY_HFD_DATASET_ROOT:-${WORLDFOUNDRY_DATA_DIR}/datasets}"
export WORLDFOUNDRY_ARTIFACT_DIR="${WORLDFOUNDRY_ARTIFACT_DIR:-${WORLDFOUNDRY_HOME}/artifacts}"
export HF_HOME="${HF_HOME:-${WORLDFOUNDRY_HOME}/huggingface}"
export HF_HUB_CACHE="${HF_HUB_CACHE:-${HF_HOME}/hub}"

mkdir -p \
  "${WORLDFOUNDRY_HFD_ROOT}" \
  "${WORLDFOUNDRY_HFD_DATASET_ROOT}" \
  "${WORLDFOUNDRY_CACHE_DIR}/repos" \
  "${WORLDFOUNDRY_ARTIFACT_DIR}/runs"

On shared machines, set roots through bootstrap or Workspace flags:

bash scripts/setup/bootstrap_worldfoundry.sh \
  --home /path/to/worldfoundry-home \
  --data-root /path/to/worldfoundry-data \
  --model-root /path/to/worldfoundry-models \
  --artifact-root /path/to/worldfoundry-artifacts
source tmp/worldfoundry_unified_env.sh

parent/
  WorldFoundry/
  ckpt/
  data/

When WORLDFOUNDRY_CKPT_DIR / WORLDFOUNDRY_DATA_DIR are unset, scripts/workspace/run_workspace.sh uses those sibling directories if they exist. Prefer explicit roots in CI:

bash scripts/workspace/run_workspace.sh \
  --ckpt-dir /path/to/ckpt \
  --data-dir /path/to/data

Path naming

HF model org/name — local directory org--name. Example: Skywork/Matrix-Game-2.0 → Skywork--Matrix-Game-2.0.
HF dataset org/name — local directory org__name. Example: lerobot/libero → lerobot__libero.
GitHub owner/repo — often owner--repo. Example: Lifelong-Robot-Learning/LIBERO → Lifelong-Robot-Learning--LIBERO.

Follow the path field in catalog YAML or local_assets.example.yaml. Some embodied benchmarks still use legacy paths such as cache/vla_va_wam/hf_datasets/org--name; mirror that layout or override the path in your manifest.

2. Where to look up required assets

Asset requirements live in manifests so docs, TUI, CLI, and runners describe the same run. Prefer the CLI summary first; open YAML when you need the exact source declaration.

Worked example: `matrix-game-2` (model checkpoint)

worldfoundry/data/models/catalog/world_models/matrix-game-2.yaml

id: matrix-game-2
name: Matrix-Game 2.0
checkpoints:
- Skywork/Matrix-Game-2.0
checkpoint:
  repos:
  - id: Skywork/Matrix-Game-2.0
    sha: f1729d99a80e0f07993a77d7dad4a3190e23c2c8
    gated: false
    license: mit
  status: confirmed_public_hf
runtime_profile: runtime-profile:matrix-game-2-universal-ref-image-seed42-15f
official_sources:
  huggingface:
  - repo_id: Skywork/Matrix-Game-2.0
    type: model
    status: confirmed

checkpoints / checkpoint.repos[].id is what you download; sha pins the revision; runtime_profile points at expected local paths and env. Same facts via CLI:

worldfoundry-eval zoo model-show --model-id matrix-game-2 --json

Local layout after staging:

${WORLDFOUNDRY_HFD_ROOT}/hub/models--Skywork--Matrix-Game-2.0/
# or:
${WORLDFOUNDRY_CKPT_DIR}/Skywork--Matrix-Game-2.0/

Worked example: `libero` (benchmark assets)

worldfoundry/data/benchmarks/catalog/embodied/libero.yaml

id: libero
name: LIBERO
official_sources:
  github:
    url: https://github.com/Lifelong-Robot-Learning/LIBERO
  huggingface_datasets:
  - repo_id: yifengzhu-hf/LIBERO-datasets
    revision: f13aa24a3da8c43c7225569f28c562979fa0e35a
  - repo_id: lerobot/libero
    revision: 1595a93b43aa055e55c127a4f0b4a99bb8035447
dataset_refs:
- repo_id: yifengzhu-hf/LIBERO-datasets
  path: cache/vla_va_wam/hf_datasets/yifengzhu-hf--LIBERO-datasets
- repo_id: lerobot/libero
  path: cache/vla_va_wam/hf_datasets/lerobot--libero
runner:
  runtime:
    root_env: WORLDFOUNDRY_LIBERO_ROOT
    results_path_env: WORLDFOUNDRY_LIBERO_RESULTS_PATH
    required_assets:
    - LIBERO dataset root or LeRobot conversion
    - suite-specific policy checkpoint
    - official rollout logs/result dump

dataset_refs[].repo_id is the HF download; path is the expected relative layout under your data root; required_assets / *_env name the rest. Merge catalog + task + profile into one checklist:

worldfoundry-eval zoo benchmark-show --benchmark-id libero --json

python scripts/setup/prepare_benchmark_assets.py \
  --benchmark-id libero \
  --json

Planner fields to read: assets.data, assets.checkpoints, env.api_or_secret, download_hints.hf, commands.official_runtime, commands.official_result_import.

3. Model checkpoints (inference)

Perception and 3D visualization checkpoints

These in-tree runtimes keep checkpoint locations in the shared base-model asset registry. Source code does not assume a checkout-specific absolute path.

Capability

sam2
OverrideWORLDFOUNDRY_SAM2_CKPT
Official source: HF facebook/sam2.1-hiera-base-plus. Expected file: sam2.1_hiera_base_plus.pt
Default location ${WORLDFOUNDRY_HFD_ROOT}/facebook--sam2.1-hiera-base-plus/
mobile_sam
OverrideWORLDFOUNDRY_MOBILE_SAM_CKPT
Official source: GitHub ChaoningZhang/MobileSAM weights/. Expected file: mobile_sam.pt
Default location ${WORLDFOUNDRY_CKPT_DIR}/MobileSAM/
repvit_sam
OverrideWORLDFOUNDRY_REPVIT_SAM_CKPT
Official source: GitHub THU-MIG/RepViT release v1.0. Expected file: repvit_sam.pt
Default location ${WORLDFOUNDRY_CKPT_DIR}/RepViT/
midas_v21_small_256
OverrideWORLDFOUNDRY_MIDAS_V21_SMALL_CKPT
Official source: GitHub isl-org/MiDaS release v2_1. Expected file: midas_v21_small_256.pt
Default location ${WORLDFOUNDRY_CKPT_DIR}/
unidepth_v2_vitl14
OverrideWORLDFOUNDRY_UNIDEPTH_V2_VITL14_MODEL_DIR
Official source: HF lpiccinelli/unidepth-v2-vitl14. Expected files: config.json, model.safetensors
Default location ${WORLDFOUNDRY_HFD_ROOT}/lpiccinelli--unidepth-v2-vitl14/
unik3d_vitl
OverrideWORLDFOUNDRY_UNIK3D_VITL_MODEL_DIR
Official source: HF lpiccinelli/unik3d-vitl. Expected files: config.json, model.safetensors
Default location ${WORLDFOUNDRY_HFD_ROOT}/lpiccinelli--unik3d-vitl/

UniDepth V2 and UniK3D are released under CC-BY-NC-4.0. Review the upstream non-commercial terms before downloading or redistributing their weights.

Inspect the exact URLs, resolved paths, size checks, and export commands without downloading:

worldfoundry-eval models assets \
  --capability sam2 \
  --capability mobile_sam \
  --capability repvit_sam \
  --capability midas_v21_small_256 \
  --capability unidepth_v2_vitl14 \
  --capability unik3d_vitl \
  --json

To materialize missing files, add --execute-downloads. HF_ENDPOINT is honored for the SAM2, UniDepth V2, and UniK3D Hugging Face assets. MobileSAM, RepViT-SAM, and MiDaS are downloaded from their official GitHub repository or release URLs:

export HF_ENDPOINT=https://hf-mirror.com
worldfoundry-eval models assets \
  --capability sam2 \
  --capability mobile_sam \
  --capability repvit_sam \
  --capability midas_v21_small_256 \
  --capability unidepth_v2_vitl14 \
  --capability unik3d_vitl \
  --execute-downloads

Plan only, then execute after you accept storage and license:

worldfoundry-eval zoo model-download \
  --model-id matrix-game-2 \
  --cache-dir "${WORLDFOUNDRY_HFD_ROOT}" \
  --check-local \
  --json

worldfoundry-eval zoo model-download \
  --model-id matrix-game-2 \
  --cache-dir "${WORLDFOUNDRY_HFD_ROOT}" \
  --execute \
  --disable-xet \
  --check-local \
  --json

Alternatives:

bash scripts/inference/prepare_model_infer.sh matrix-game-2 --download

hf download Skywork/Matrix-Game-2.0 \
  --revision f1729d99a80e0f07993a77d7dad4a3190e23c2c8 \
  --local-dir "${WORLDFOUNDRY_HFD_ROOT}/Skywork--Matrix-Game-2.0"

Worked example: Echo-Memory

Echo recipes share the Wan2.1 T2V 1.3B backbone but require different files under Echo-Team/Echo-Memory. As of 2026-07-20, only context_k1/epoch-0.safetensors remains on the official HF main branch. Other Echo model IDs stay in the catalog with exact expected filenames, but their upstream state is unreleased_by_upstream or retracted_misaligned_by_upstream; do not substitute K=1 weights for them.

Stage the currently public recipe and its pinned backbone into the runtime layout, then create the normal HFD aliases without copying tensors:

export HF_ENDPOINT=https://hf-mirror.com

hf download Echo-Team/Echo-Memory \
  context_k1/epoch-0.safetensors \
  --revision 7645f33efbfd02c58dc471570d0c7bd6a50eec83 \
  --local-dir "${WORLDFOUNDRY_CKPT_DIR}/Echo-Memory"

hf download Wan-AI/Wan2.1-T2V-1.3B \
  --revision 37ec512624d61f7aa208f7ea8140a131f93afc9a \
  --local-dir "${WORLDFOUNDRY_CKPT_DIR}/Wan2.1-T2V-1.3B"

bash scripts/setup/link_hf_checkpoints.sh \
  --repo Echo-Team/Echo-Memory=Echo-Memory \
  --repo Wan-AI/Wan2.1-T2V-1.3B=Wan2.1-T2V-1.3B

The standard checker validates the recipe-specific filename as well as the repository, so a cache containing only K=1 cannot make a K=20 or SSM model look ready:

worldfoundry-eval zoo model-download \
  --model-id echo-memory-context-k1 \
  --check-local \
  --json

Researchers with an unpublished checkpoint can place it at the exact checkpoint_path shown by that model's runtime profile and create the same HFD alias. Keep the catalog entry blocked until strict checkpoint loading and CUDA artifact validation pass.

Worked example: Matrix-Game 3.5

The first- and third-person model IDs share Wan2.2, UMT5, and DA3 assets but bind different files from RiemannDynamics/Matrix-Game-3.5-Base. Download both files once so either immutable recipe can resolve through the standard HFD alias. Set HF_ENDPOINT=https://hf-mirror.com first when using HF-Mirror. The DA3 checkpoint has its own CC-BY-NC-4.0 license even though the Matrix-Game and Wan checkpoints are Apache-2.0; follow each dependency's upstream terms.

hf download RiemannDynamics/Matrix-Game-3.5-Base \
  --revision 40c172355efa32d4e2a44076569e310807788f8a \
  --include first-person.safetensors \
  --include third-person.safetensors \
  --local-dir "${WORLDFOUNDRY_HFD_ROOT}/RiemannDynamics--Matrix-Game-3.5-Base"

hf download Wan-AI/Wan2.2-TI2V-5B \
  --revision 921dbaf3f1674a56f47e83fb80a34bac8a8f203e \
  --include 'diffusion_pytorch_model*.safetensors' \
  --include models_t5_umt5-xxl-enc-bf16.pth \
  --include Wan2.2_VAE.pth \
  --include 'google/umt5-xxl/*' \
  --local-dir "${WORLDFOUNDRY_HFD_ROOT}/Wan-AI--Wan2.2-TI2V-5B"

hf download depth-anything/DA3NESTED-GIANT-LARGE-1.1 \
  --revision b2359bdf726fb44ef62acca04d629dcf158053e7 \
  --include config.json \
  --include model.safetensors \
  --local-dir "${WORLDFOUNDRY_HFD_ROOT}/depth-anything--DA3NESTED-GIANT-LARGE-1.1"

Verify both recipes without loading model tensors:

worldfoundry-eval zoo model-download \
  --model-id matrix-game-3.5-first-person \
  --check-local \
  --json

worldfoundry-eval zoo model-download \
  --model-id matrix-game-3.5-third-person \
  --check-local \
  --json

Worked example: Cosmos 1 and 2

GEN3C uses four explicit assets: the 7B transformer, Tokenize1 codec, T5-11B, and MoGe depth model. Cosmos Predict2 uses its selected Video2World transformer and tokenizer/tokenizer.pth, plus the same T5-11B encoder. Predict2 repositories are gated, so authenticate before using the mirror.

export HF_ENDPOINT=https://hf-mirror.com

hf download nvidia/GEN3C-Cosmos-7B \
  --revision 9bcfdb4f3924f41376daeadf6200826c12a3bf8e \
  --include model.pt \
  --local-dir "${WORLDFOUNDRY_HFD_ROOT}/nvidia--GEN3C-Cosmos-7B"

hf download nvidia/Cosmos-Predict2-2B-Video2World \
  --revision f50c09f5d8ab133a90cac3f4886a6471e9ba3f18 \
  --include model-720p-16fps.pt \
  --include tokenizer/tokenizer.pth \
  --local-dir "${WORLDFOUNDRY_HFD_ROOT}/nvidia--Cosmos-Predict2-2B-Video2World"

hf download google-t5/t5-11b \
  --revision 90f37703b3334dfe9d2b009bfcbfbf1ac9d28ea3 \
  --include pytorch_model.bin --include config.json \
  --include spiece.model --include tokenizer.json \
  --local-dir "${WORLDFOUNDRY_HFD_ROOT}/google-t5--t5-11b"

Download nvidia/Cosmos-Tokenize1-CV8x8x8-720p and Ruicheng/moge-vitl for GEN3C as declared in its runtime profile. For Predict2 14B, switch to nvidia/Cosmos-Predict2-14B-Video2World revision 03b03a377fede782647afac998f674d9f358e319.

Worked example: Cosmos 2.5

Cosmos Predict and Transfer share the Predict 2B tokenizer.pth Wan codec and the Reason1 language model. Download only the selected transformer plus those shared assets. Transfer currently uses the exact official general/edge checkpoint revision; directory presence without that file is not readiness. Set HF_ENDPOINT=https://hf-mirror.com when the mirror is required.

hf download nvidia/Cosmos-Predict2.5-2B \
  --revision f176dc95b4a70f53ce01c4b302851595e7322b00 \
  --include tokenizer.pth \
  --include 'base/post-trained/81edfebe-bd6a-4039-8c1d-737df1a790bf_ema_bf16.pt' \
  --local-dir "${WORLDFOUNDRY_HFD_ROOT}/nvidia--Cosmos-Predict2.5-2B"

hf download nvidia/Cosmos-Reason1-7B \
  --revision 375e24000b24baed78f4618d3dd779e47cd96323 \
  --include 'model*.safetensors' \
  --include model.safetensors.index.json \
  --include tokenizer.json \
  --include tokenizer_config.json \
  --include chat_template.json \
  --include config.json \
  --local-dir "${WORLDFOUNDRY_HFD_ROOT}/nvidia--Cosmos-Reason1-7B"

hf download nvidia/Cosmos-Transfer2.5-2B \
  --revision bd963eabcfc2d61dc4ea365cacf41d45ac480aa5 \
  --include 'general/edge/ecd0ba00-d598-4f94-aa09-e8627899c431_ema_bf16.pt' \
  --local-dir "${WORLDFOUNDRY_HFD_ROOT}/nvidia--Cosmos-Transfer2.5-2B"

For 14B Predict, replace the transformer download with revision 71ebf3e8af30ecfe440bf0481115975fcc052b46 and file base/post-trained/e21d2a49-4747-44c8-ba44-9f6f9243715f_ema_bf16.pt from nvidia/Cosmos-Predict2.5-14B; keep the same Reason1 and VAE assets.

For other models, use the repo_id / revision from that model's catalog entry the same way. On a shared machine with pre-staged snapshots, set WORLDFOUNDRY_MODEL_DIR and symlink HF cache names instead of copying weights:

bash scripts/setup/link_hf_checkpoints.sh \
  --ckpt-dir "${WORLDFOUNDRY_CKPT_DIR}" \
  --hfd-root "${WORLDFOUNDRY_HFD_ROOT}" \
  --hf-hub-cache "${HF_HUB_CACHE}" \
  --repo Skywork/Matrix-Game-2.0=Matrix-Game-2.0 \
  --default-world

WorldFoundry prefers native HF loading (from_pretrained, snapshot_download, HF_HOME / HF_HUB_CACHE). ${WORLDFOUNDRY_CKPT_DIR} symlinks are for upstream runtimes that need a fixed directory layout. Metric weights for VBench-family scorers are listed on the relevant Benchmark Hub and Metrics pages, or in the planner JSON under assets.checkpoints.

4. Benchmark datasets

WorldFoundry does not bulk-download every benchmark dataset. Generate a plan, then run the download_hints.hf lines (or the official URL in source_provenance):

python scripts/setup/prepare_benchmark_assets.py \
  --benchmark-id <benchmark-id> \
  --json

python scripts/setup/prepare_benchmark_assets.py \
  --benchmark-id <benchmark-id> \
  --write-env "${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}/<benchmark-id>.env" \
  --create-dirs

source "${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}/<benchmark-id>.env"

Manual dataset example:

hf download Howieeeee/WorldScore \
  --repo-type dataset \
  --local-dir "${WORLDFOUNDRY_DATA_DIR}/datasets/Howieeeee__WorldScore"

For gated datasets, accept the upstream license and set HF_TOKEN first. Per-benchmark layouts and run requirements live on the Benchmark Hub pages.

5. `local_assets` manifest

Copy the example outside git and point one env var at it:

cp worldfoundry/data/benchmarks/local_assets.example.yaml \
   "${WORLDFOUNDRY_HOME}/local_assets.yaml"

export WORLDFOUNDRY_LOCAL_ASSET_MANIFEST="${WORLDFOUNDRY_HOME}/local_assets.yaml"

repo — Existing source/runtime root. Typical command: set WORLDFOUNDRY_<BENCHMARK>_ROOT=<path>.
dataset — HF dataset snapshot. Typical command: hf download <id> --repo-type dataset --local-dir <path>.
checkpoint — Model weights. Typical command: hf download <id> --local-dir <path>.
simulator_asset — Simulator files. Typical command: manual install per benchmark docs.
result_dump — Upstream official results. Typical command: copy after running the upstream evaluator.

Embodied simulator roots and helper scripts are covered in Embodied official runtime.