---
title: Environments
description: Choose the dependency stack for each model family, benchmark runtime, and validation stage.
---

## Introduction

An environment is the dependency and launch context expected by a model or benchmark: Python packages, CUDA/Torch bucket, optional system tools, checkpoint layout, device assumptions, and command shape.

The repository still uses `runtime_profile` as a metadata field because it points to a concrete environment record in `worldfoundry/data/models/runtime/profiles/<model-id>.yaml`. In reader-facing docs, this page calls the same concept an environment.

WorldFoundry uses conda as the single supported environment path. The documented workflow creates one named conda environment for the main framework and separate conda environments only when an upstream simulator or official runtime requires isolation.

1. Start with `bash scripts/setup/bootstrap_worldfoundry.sh` for model inference.
2. Use `bash scripts/setup/model_env_install.sh --list` to inspect every model-to-env mapping, or `--model <model-id>` when you need the exact env for one model.
3. Stay in the unified env when the resolved profile is `worldfoundry-unified-<tier>`.
4. Switch to a dedicated env only when `runtime/environments/<category>/<model-id>.yaml` records an ABI or simulator constraint.
5. Use benchmark-specific scripts only for official metrics, reference metrics, or physics stacks.

## Python install surfaces

`pyproject.toml` exposes two intentionally different dependency surfaces:

- **Optional dependencies (extras)** are the public, wheel-visible install surface for users and contributors. Install the smallest extra that matches the feature you need, for example `python -m pip install -e ".[ui]"`.
- **Dependency groups** are source-checkout tooling and resolver buckets. They are not wheel extras and are not selected with `.[name]`. With a PEP 735-capable pip, use a command such as `python -m pip install --group lint`; environment tooling may consume the same groups directly.

`all` is a curated general-runtime bundle, not the literal union of every extra. It deliberately excludes development tools, proprietary NVIDIA VFX bindings, training stacks, and model-specific ABI islands. In the catalog below, “In `all`” means that every package name declared by that extra is represented in `all`; install the named extra as well when its tighter version constraints are part of the runtime contract.

<KvCatalog heading="Extra" vars rows={[
    { name: <><code>api</code></>, description: "Hosted model API clients and image/request helpers.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[api]</code></> }] },
    { name: <><code>apple_pi</code></>, description: "Apple-PI evaluation runtime, judge clients, and media helpers.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[apple_pi]</code></> }] },
    { name: <><code>hf</code></>, description: "Hugging Face and ModelScope asset download support.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[hf]</code></> }] },
    { name: <><code>video</code></>, description: "Broad video, media, data, and 3D runtime dependencies.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[video]</code></> }] },
    { name: <><code>vipe</code></>, description: "ViPE geometry/depth runtime and visualization stack.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[vipe]</code></> }] },
    { name: <><code>molmoact2</code></>, description: "MolmoAct2 model serving stack with its narrow Transformers contract.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[molmoact2]</code></> }] },
    { name: <><code>molmobot_pi0</code></>, description: "Pinned MolmoBot Pi0 policy runtime.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[molmobot_pi0]</code></> }] },
    { name: <><code>metrics</code></>, description: "General evaluation metrics and dataset I/O.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[metrics]</code></> }] },
    { name: <><code>distribution_metrics</code></>, description: "Perceptual and distribution metric models.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[distribution_metrics]</code></> }] },
    { name: <><code>dvlt</code></>, description: "DVLT 3D/visualization runtime.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[dvlt]</code></> }] },
    { name: <><code>ui</code></>, description: "Complete Studio/browser UI, including realtime transport dependencies.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[ui]</code></> }] },
    { name: <><code>studio_realtime</code></>, description: "Minimal WebRTC/realtime Studio transport stack.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[studio_realtime]</code></> }] },
    { name: <><code>rtx_postprocess</code></>, description: "Proprietary NVIDIA VFX post-processing; explicit opt-in only.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[rtx_postprocess]</code></> }] },
    { name: <><code>tui</code></>, description: "Textual terminal UI.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[tui]</code></> }] },
    { name: <><code>optimized_core</code></>, description: "Optional Torch-based core acceleration dependencies.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[optimized_core]</code></> }] },
    { name: <><code>lora</code></>, description: "Load and merge released PEFT LoRA adapters for inference.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[lora]</code></> }] },
    { name: <><code>profiling</code></>, description: "Model profiling helpers.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[profiling]</code></> }] },
    { name: <><code>web</code></>, description: "Minimal FastAPI web service surface.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[web]</code></> }] },
    { name: <><code>mcp</code></>, description: "Model Context Protocol server/client support.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[mcp]</code></> }] },
    { name: <><code>worldscore</code></>, description: "WorldScore evaluation runtime.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[worldscore]</code></> }] },
    { name: <><code>studio_pointcloud</code></>, description: "Point-cloud Studio visualization.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[studio_pointcloud]</code></> }] },
    { name: <><code>studio_rerun</code></>, description: "Rerun-based Studio visualization.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[studio_rerun]</code></> }] },
    { name: <><code>studio_geometry</code></>, description: "Geometry and Open3D Studio visualization.", reads: [{ label: "In all", value: "Yes" }, { label: "Install", value: <><code>.[studio_geometry]</code></> }] },
    { name: <><code>studio_plot</code></>, description: "Plotting and color utilities for Studio.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[studio_plot]</code></> }] },
    { name: <><code>dev</code></>, description: "Build, pre-commit, and repository-pinned lint tooling.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[dev]</code></> }] },
    { name: <><code>test</code></>, description: "Public CPU inference and packaging tests; no Torch or model downloads required.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[test]</code></> }] },
    { name: <><code>eval_core</code></>, description: "Optional CPU evaluation dependencies.", reads: [{ label: "In all", value: "No" }, { label: "Install", value: <><code>.[eval_core]</code></> }] },
    { name: <><code>all</code></>, description: "Curated general runtime bundle described above.", reads: [{ label: "Install", value: <><code>.[all]</code></> }] }
  ]} />

The source-only dependency groups are narrower resolver building blocks:

- `lint` — Repository-pinned pre-commit and Ruff toolchain.
- `flash_attn_fa25` — Flash-attention bucket for FA 2.5-compatible environments.
- `flash_attn_fa28` — Flash-attention bucket for FA 2.8-compatible environments.
- `runtime_clip_bundle` — CLIP-oriented runtime compatibility bundle.
- `runtime_timm_bundle` — Timm/Torch runtime compatibility bundle.
- `three_d_core` — Shared point-cloud and 3D geometry packages.
- `transformers_high` — Current Transformers/Diffusers compatibility bucket.
- `transformers_low` — Legacy or model-constrained Transformers compatibility bucket.

These groups select Python requirements only. CUDA/Torch wheel selection, native extension builds, and isolated model environments still go through the setup scripts and runtime profiles documented below.

## Clone-to-run setup scripts

Run these scripts from the repository root. They are part of the public release
surface, not local machine notes.

- **`scripts/setup/bootstrap_worldfoundry.sh`** — First command after cloning the repo. Creates/verifies the unified env, writes `tmp/worldfoundry_unified_env.sh`, optionally installs model-specific envs, optionally prepares model assets, and prints the Workspace launch command.
- **`scripts/setup/unified_install.sh`** — Main GPU runtime only. Creates `worldfoundry-unified-<cuda-tier>` and installs `requirements/worldfoundry-unified.txt`, PyTorch CUDA wheels, optional flash-attn, and import/CUDA checks.
- **`scripts/setup/model_env_install.sh`** — Per-model environment resolution. Reads `worldfoundry/data/models/runtime/environments/**`; routes compatible profiles back to the unified env and creates dedicated envs only for hard ABI conflicts.
- **`scripts/inference/prepare_model_infer.sh`** — Checkpoint/Hugging Face preparation per model. Defaults to a plan/check-local flow. Add `--download` only after reviewing license, gated access, and storage requirements.
- **`scripts/workspace/run_workspace.sh`** — Start the browser Workspace from an activated runtime. Keeps `PYTHONPATH=.`, `WORLDFOUNDRY_WORKSPACE_MAX_JOBS`, and `WORLDFOUNDRY_CKPT_DIR` explicit.

The unified installer selects a Torch range that exists on the resolved wheel
index: cu121 uses Torch 2.4–2.5, cu124 uses 2.4–2.6, and cu128 uses 2.7 or
newer within the repository upper bound. After the CUDA-index install, the
exact Torch/Torchvision/Torchaudio versions constrain the remaining PyPI pass
so indirect dependencies cannot replace the selected CUDA build. On hosts
without `nvidia-smi`, bootstrap explicitly uses the cu128 wheel index while
enabling `--allow-no-cuda` and skipping flash-attn; direct installer calls with
`--cuda auto` instead fail fast and ask for an explicit tier. If another
selected extra requires a newer Torch than that tier publishes, dependency
resolution fails explicitly instead of falling back to a PyPI CPU/different
CUDA wheel.

Recommended fresh-clone path:

```bash
git clone https://github.com/OpenEnvision/WorldFoundry.git
cd WorldFoundry

bash scripts/setup/bootstrap_worldfoundry.sh
source tmp/worldfoundry_unified_env.sh
conda activate "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}"
```

Environment prefixes are machine-local artifacts. If an existing checkout reports a missing `python3.x`, missing native module, or
`libssl`/`libcrypto` error, recreate the environment or run the public verifier:

```bash
bash scripts/setup/bootstrap_worldfoundry.sh --verify-only
```

Review a model before downloading checkpoints:

```bash
bash scripts/setup/bootstrap_worldfoundry.sh \
  --with-model matrix-game-2 \
  --prepare-model matrix-game-2
```

Download public assets only when ready:

```bash
export HF_TOKEN=<your-token-if-needed>
bash scripts/setup/bootstrap_worldfoundry.sh \
  --with-model matrix-game-2 \
  --prepare-model matrix-game-2 \
  --download-model-assets
```

`--download-model-assets` forwards to each model's preparation script. It does
not bypass Hugging Face gates; users must accept model terms upstream and
provide `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN` themselves.

For a multi-model workstation, install the unified env once and then verify
exceptions explicitly:

```bash
bash scripts/setup/bootstrap_worldfoundry.sh \
  --with-model lingbot-world \
  --with-model octo \
  --prepare-model lingbot-world \
  --prepare-model octo
```

Start the Workspace after setup:

```bash
source tmp/worldfoundry_unified_env.sh
conda activate "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}"
PYTHONPATH=. WORLDFOUNDRY_WORKSPACE_MAX_JOBS=8 \
python -m worldfoundry.studio.serving.workspace --host 127.0.0.1 --port 7870
```

Use explicit roots when datasets or checkpoints should live on shared storage:

```bash
bash scripts/setup/bootstrap_worldfoundry.sh \
  --home /path/to/worldfoundry-home \
  --data-root /path/to/worldfoundry-data \
  --model-root /path/to/worldfoundry-models
```

## Runtime variables

`bootstrap_worldfoundry.sh` and `unified_install.sh` write the same sourceable env
file. Keep this file local to the machine; it contains paths but no secrets.

<div className="pi-kv-catalog is-vars not-prose">
  <section className="pi-kv-group">
    <h3>Variable</h3>
    <ul>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>WORLDFOUNDRY_HOME</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            yes
          </span>
        </div>
        <p>Root for local runtime state.</p>
      </li>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>WORLDFOUNDRY_REPO_ROOT</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            yes
          </span>
        </div>
        <p>Absolute path to the checked-out WorldFoundry repository.</p>
      </li>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>WORLDFOUNDRY_CACHE_DIR</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            yes
          </span>
        </div>
        <p>General cache root.</p>
      </li>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>WORLDFOUNDRY_DATA_DIR</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            yes
          </span>
        </div>
        <p>Dataset and benchmark data root.</p>
      </li>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>WORLDFOUNDRY_MODEL_DIR</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            yes
          </span>
        </div>
        <p>Model asset root.</p>
      </li>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>WORLDFOUNDRY_CKPT_DIR</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            yes
          </span>
        </div>
        <p>Compatibility checkpoint root for non-HF layouts and soft links.</p>
      </li>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>WORLDFOUNDRY_ARTIFACT_DIR</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            yes
          </span>
        </div>
        <p>Generated outputs and validation artifacts.</p>
      </li>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>WORLDFOUNDRY_CONDA_ENVS_ROOT</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            yes
          </span>
        </div>
        <p>Parent directory for unified and dedicated conda envs.</p>
      </li>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>WORLDFOUNDRY_UNIFIED_ENV_PREFIX</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            yes
          </span>
        </div>
        <p>Absolute path of the main conda env.</p>
      </li>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>WORLDFOUNDRY_CUDA_PROFILE</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            yes
          </span>
        </div>
        <p>Resolved CUDA wheel tier, normally <code>cu128</code> on CUDA 12.8+ hosts.</p>
      </li>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>HF_HOME</code>, <code>HF_HUB_CACHE</code>, <code>HF_DATASETS_CACHE</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            yes
          </span>
        </div>
        <p>Hugging Face cache roots when using a WorldFoundry-managed cache.</p>
      </li>
      <li className="pi-kv-row">
        <div className="pi-kv-head">
          <div className="pi-kv-names">
            <code>HF_TOKEN</code>, <code>HUGGING_FACE_HUB_TOKEN</code>
          </div>
          <span className="pi-kv-default">
            <span>Written by setup</span>
            no
          </span>
        </div>
        <p>Optional user-provided credentials for gated assets. Never commit these.</p>
      </li>
    </ul>
  </section>
</div>

Prefer native Hugging Face loading (`from_pretrained`, `snapshot_download`, and
standard HF cache variables) for public checkpoints. Use `WORLDFOUNDRY_CKPT_DIR`
for upstream runtimes that require a fixed directory layout or for local soft
links that preserve official paths without duplicating large files.

### Benchmark dataset layouts

`worldfoundry-eval dataset locate <org/name>` resolves an existing dataset
without network access. It checks the per-dataset environment override first,
then local asset/data manifests, a direct data root, and finally Hugging Face
cache snapshots. Direct roots accept `org/name`, `org--name`, and nested
`hfd_datasets` layouts; hub caches use the standard
`datasets--org--name/snapshots/<revision>` layout. Use
`worldfoundry-eval dataset plan <org/name> [...]` to print deduplicated download
commands without executing them.

## Compiler caches

`worldfoundry.core.execution.compile_cache` configures persistent `torch.compile` caches
for Inductor, Triton, the CUDA driver JIT, and torch C++/CUDA extensions. The
compatibility import `worldfoundry.runtime.compile_cache` exposes the same API.
The root is `WORLDFOUNDRY_COMPILE_CACHE_DIR` when set, otherwise
`${WORLDFOUNDRY_CACHE_DIR}/compile`. Generated-code caches are partitioned by a
Torch/Triton/cuDNN/Python/accelerator fingerprint. Explicit
`TORCHINDUCTOR_CACHE_DIR`, `TRITON_CACHE_DIR`, `TORCH_EXTENSIONS_DIR`, and
`CUDA_CACHE_PATH` values take precedence when writable; an unwritable cache
falls back to a process-local temporary directory with a warning.

On a multi-node cluster, use node-local storage rather than a shared NFS or
project mount. The fingerprint separates incompatible software and accelerator
stacks, but it does not isolate concurrent writers on different nodes:

```bash
export WORLDFOUNDRY_COMPILE_CACHE_DIR=/local-ssd/${USER}/worldfoundry-compile
```

Autotune defaults are applied with `setdefault`, so values exported before
launch win. WorldFoundry defaults to
`TORCHINDUCTOR_AUTOTUNE_LOCAL_CACHE=1` and
`TORCHINDUCTOR_AUTOTUNE_REMOTE_CACHE=0`; opt in to a remote autotune cache only
when the cluster provides a compatible service.

## Logging

The CLI flags and environment variables below feed the same opt-in logging
pipeline, `worldfoundry.core.observability.logging_setup.configure_logging`. Explicit CLI
flags take precedence over inherited environment values.

<KvCatalog heading="Setting" vars rows={[
    { name: "Level", description: <>{"Console and file threshold; the CLI accepts "}<code>DEBUG</code>{", "}<code>INFO</code>{", "}<code>WARNING</code>{", "}<code>ERROR</code>{", or "}<code>CRITICAL</code>{"."}</>, reads: [{ label: "CLI", value: <><code>--log-level</code></> }, { label: "Environment", value: <><code>WORLDFOUNDRY_LOG_LEVEL</code></> }] },
    { name: "File sink", description: <>{"Optional rotating file path. Output-owning CLI commands create a per-run "}<code>events.jsonl</code>{" when neither is set."}</>, reads: [{ label: "CLI", value: <><code>--log-file</code></> }, { label: "Environment", value: <><code>WORLDFOUNDRY_LOG_FILE</code></> }] },
    { name: "JSON Lines", description: "Makes the file sink JSON Lines; console output remains text.", reads: [{ label: "CLI", value: <><code>--log-json</code></> }, { label: "Environment", value: <><code>WORLDFOUNDRY_LOG_JSON</code></> }] },
    { name: "Child context", description: <>{"JSON object containing structured correlation fields such as "}<code>run_id</code>{", "}<code>job_id</code>{", "}<code>benchmark_id</code>{", and "}<code>model_id</code>{"."}</>, reads: [{ label: "Environment", value: <><code>WORLDFOUNDRY_LOG_CONTEXT</code></> }] }
  ]} />

Framework-owned workers receive structured context through
`log_context_environment()`. `WORLDFOUNDRY_RUN_ID` is also exported by
output-owning CLI operations for operator visibility, but it is not a
replacement for `WORLDFOUNDRY_LOG_CONTEXT`.

Structured log messages and fields redact sensitive key names, bearer tokens,
common OpenAI/Hugging Face/GitHub/Slack/AWS token formats, and compact JWTs.
Raw stdout/stderr capture remains fidelity-preserving and may use a separate
line or argument scrubber; do not assume every captured byte passed through the
structured logger. Loguru keeps native time/count retention semantics, while
the stdlib fallback interprets retention as a rotated backup-file count.

## Dedicated model environment exceptions

Start from `worldfoundry-unified-<cuda-tier>` for every model. Create a
dedicated environment only for the profiles below, where the upstream runtime
has a real ABI or framework-family conflict with the unified CUDA stack.

Install one exception with:

```bash
bash scripts/setup/model_env_install.sh --model <model-id>
```

For model setup, prefer `scripts/inference/prepare_model_infer.sh`; it installs
the resolved environment first and then checks or downloads assets. Use
`scripts/setup/model_env_install.sh` directly only when you want to prepare the
conda env without touching checkpoints.

<DedicatedEnvCatalog />

EvalCrafter is the only benchmark with a WorldFoundry-managed dedicated metric
profile. Other benchmark-specific native stacks are listed below and are not
claimed as configured until their own preflight passes.

## Unified environment with extra runtime requirements

The models below should still use `worldfoundry-unified-<cuda-tier>`, but their
docs should call out extra local assets, compiled wheels, or external services.
These are not reasons to clone an external repository; the code path is in-tree.

- **Unified-env WRBench camera/world integrations (EasyAnimate, Hunyuan WorldPlay, HunyuanWorld-Voyager, InSpatio-World, Matrix-Game 2/3, ReCamMaster, SANA-WM, ATI, HyDRA, Spatia, minWM, MagicWorld, LiveWorld, VerseCrafter, VideoX-Fun camera variants, and the HY-World renderer)** — Extra requirement: Hugging Face checkpoints declared by each profile; Spatia's default MapAnything checkpoint is non-commercial research only. Notes: These resolve to `worldfoundry-unified-<cuda-tier>`. Every model keeps an independent in-tree inference binding. Reusable Wan2.1, MapAnything, UniCeption, Uni3C, Depth Pro, STream3R, SAM3 video segmentation, Qwen3-VL entity extraction, and point-cloud projection components live under `base_models`; runtime config lives under `worldfoundry/data`. Runtime setup never clones source repositories. AC3D, Cosmos3, GEN3C, Hunyuan GameCraft, and both LingBot routes use the dedicated environments listed above.
- **SkyReels V3** — Extra requirement: CUDA compiler, flash-attn, and torchao for the official 8-GPU USP path. Notes: Use `unified_install.sh` without `--skip-flash-attn` or build flash-attn through `scripts/setup/install_flash_attn.sh`.
- **Matrix-Game-3** — Extra requirement: Flash-attn. Notes: FA3 may be requested by config; FA2 fallback is acceptable on A100 validation hosts.
- **HunyuanWorld-Mirror** — Extra requirement: CUDA/PyTorch-matched `gsplat` wheel. Notes: Remains a unified-env model when the wheel matches the active torch stack.
- **pixelSplat** — Extra requirement: Local Gaussian rasterization extension and `re10k.ckpt`. Notes: The model wrapper is in tree; only the extension/checkpoint are local prerequisites.
- **LingBot-Map** — Extra requirement: Optional FlashInfer. Notes: The wrapper defaults to SDPA, so FlashInfer is not mandatory for baseline inference.
- **OpenPI / MME-VLA** — Extra requirement: JAX policy dependencies, `gsutil` for some OpenPI checkpoint shards, and optional OpenPI-style websocket or robot-simulator services for full policy rollout. Notes: WorldFoundry keeps code in tree; these requirements are runtime services or checkpoint-transfer tools, not external repo clones. LAPA uses the isolated environment listed above.
- **Solaris** — Extra requirement: JAX/Orbax checkpoint loading and official HF evaluation fixtures. Notes: Uses the unified env in WorldFoundry; document the dataset/checkpoint layout rather than a separate conda env.

## Benchmark metric environments

Most benchmark official validation runs and official-result normalizers run in the
unified environment. Full official metric suites can require a separate conda
profile when their dependency stack would disturb model inference. Install those
profiles through the same public setup entrypoint:

The complete per-benchmark mapping for all 42 Video Generation and World Model
entries is in the [benchmark runtime environment matrix](/docs/evaluation/benchmark-hub/runtime-environments).
That matrix also records external API services, native extensions, checkpoint
stacks, and the currently verified scope; `needs_new_env: false` alone is not a
full-suite readiness claim.

```bash
bash scripts/setup/model_env_install.sh --model evalcrafter
```

EvalCrafter's supported three-metric CLIP path and `final_result.txt` import run
in `worldfoundry-unified-<tier>`. The separate
`worldfoundry-evalcrafter-metrics` profile mirrors the official revision's
Python 3.9.17, pip 23.2.1, Torch 2.0.1, torchvision 0.15.2, TensorFlow 2.12.0,
PaddlePaddle-GPU 2.5.1, MMCV 2.0.1, and MMAction2 1.1.0 package pins. It exists
to prepare the upstream dependency surface, not to imply that WorldFoundry
orchestrates the full scorer.

- **EvalCrafter** — Environment boundary: Unified env for the three official CLIP-derived metrics and result import; official legacy environment for preparing the external full stack. Verified scope: The bounded metric path is verified. Environment preparation is documented, but complete 17-metric recomputation and leaderboard output remain unsupported.
- **iWorld-Bench** — Environment boundary: Unified env, including the pinned in-tree ViPE native sources and CUDA build. `WORLDFOUNDRY_IWORLD_BENCH_PYTHON` is only an optional override for a non-standard ABI-compatible Python. Verified scope: One real 16-frame video passed the official `memory_ability` component path. The bundled three-prompt coverage and all nine component metrics were not run, so full-suite and leaderboard validity remain false.
- **VBench / VBench-2.0 / VBench++** — Environment boundary: Unified env plus dimension-specific checkpoints and optional perception packages. Verified scope: Bounded official dimensions only; each selected dimension must pass preflight.
- **T2V-SafetyBench** — Environment boundary: Unified client environment plus a user-provided judge API endpoint/key. Verified scope: API failure is fail-closed; no judge API result is claimed from local fixture tests.

A separate environment is never inferred from a successful import. The catalog
and runtime profile must name its Python executable or setup command, assets,
and verified scope. If no reproducible environment recipe exists, the affected
metric remains blocked rather than being reported through a fallback score.

The in-tree code keeps reusable foundation models under `worldfoundry/base_models`.
These components are available for future full-suite work; their presence does
not mean the bounded EvalCrafter runner currently executes them:

- **DeepFace runtime** (`worldfoundry/base_models/perception_core/face/deepface`) — Available for future celebrity identity integration; the supported CLIP subset does not execute it.
- **DOVER runtime** (`worldfoundry/base_models/perception_core/video_quality/dover`) — Available for future video-quality integration; the supported CLIP subset does not execute it.
- **VideoMAE action recipe** (`worldfoundry/base_models/perception_core/action_recognition/videomae_mmaction`) — Only the EvalCrafter-used VideoMAEv2 config and Kinetics-400 label map are vendored. MMAction2 is installed as an environment dependency, not copied as framework source.

For the supported subset, stage CLIP ViT-B/32 under the standard checkpoint
root or set its explicit override:

```bash
export WORLDFOUNDRY_CLIP_VIT_B32_MODEL_DIR="${WORLDFOUNDRY_HFD_ROOT}/openai--clip-vit-base-patch32"
```

See the [EvalCrafter benchmark page](/docs/evaluation/benchmark-hub/evalcrafter)
for the no-proxy download and smoke command. The complete upstream suite also
expects direct `0000.mp4` through `0699.mp4` files, but WorldFoundry does not
currently claim that full path.

## WorldFoundry container

The supported image is the repository-root `docker/Dockerfile`, built through `docker/build_with_docker.sh`. Dockerfiles under `worldfoundry/base_models/perception_core/detection/yolo_world/mmyolo/docker/` (and the MMYOLO CircleCI Dockerfile) are upstream snapshot artifacts. WorldFoundry does not build or publish those images; they keep PyTorch 1.8/1.9-era CUDA bases and are not maintained against the current runtime. If you need an MMYOLO-specific image, build it from current upstream rather than this vendored copy.

## Embodied simulator environments

The host setup is Docker plus the unified WorldFoundry environment:

```bash
bash scripts/setup/bootstrap_worldfoundry.sh
source tmp/worldfoundry_unified_env.sh
docker pull ghcr.io/allenai/vla-evaluation-harness/robotwin:latest
worldfoundry-eval embodied run \
  --config worldfoundry/data/benchmarks/eval_configs/embodied/robotwin/eval.yaml \
  --pull-docker
```

Benchmark configs that have a `docker.image` entry, either directly or through
`worldfoundry/data/benchmarks/runtime_profiles/official/<benchmark>.yaml`, are
launched through `worldfoundry/evaluation/tasks/embodied/docker_runner.py`.
Inside the container, simulator dependencies are provided by the image. On the
host, only mount datasets/checkpoints/results and provide the policy server
endpoint.

## Troubleshooting

When working with complex setups involving CUDA, simulators, or external evaluators, you may encounter environment issues:

### 1. CUDA mismatch
**Symptom**: `CUDA error: no kernel image is available for execution on the device` or PyTorch cannot find a GPU.
**Solution**: Ensure your NVIDIA driver is up-to-date and supports the CUDA version installed by Conda. If you are on an older driver, you can force the installation script to use an older CUDA wheel bucket:
```bash
bash scripts/setup/unified_install.sh --cuda cu121
```

### 2. Missing system dependencies (e.g., for OpenGL/3D)
**Symptom**: Errors relating to `libGL.so.1`, `EGL`, or headless rendering failures when running embodied simulators or 3D benchmarks.
**Solution**: Install the required system-level graphics libraries. On Ubuntu/Debian:
```bash
sudo apt-get update && sudo apt-get install -y libgl1-mesa-glx libglib2.0-0
```

### 3. Flash Attention installation fails
**Symptom**: The unified install script hangs or fails during `flash-attn` compilation.
**Solution**: `flash-attn` is extremely sensitive to mismatched CUDA compiler (`nvcc`) versions. Ensure your `nvcc --version` matches the PyTorch CUDA version. Alternatively, you can disable `flash-attn` installation by passing `--skip-flash-attn` (if supported by your environment) or installing a pre-compiled wheel from the official release page.