Usage

This page is the user-facing path for running WorldFoundry. It keeps the day-one workflow in one place; deeper pages are for details and edge cases.

Most runs follow the same shape even when the model or benchmark changes. First make the Python environment importable, then put checkpoints and benchmark assets in local cache directories, then generate artifacts, and only then score those artifacts.

Workflow

1. Environment

The bootstrap step creates the default WorldFoundry runtime and writes a local shell file with the paths used by the CLI, Studio, and evaluation runners. Always source that file before running commands in a new shell; it is the piece that tells WorldFoundry where your cache, datasets, checkpoints, conda envs, and outputs live.

Start from the repository root:

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}"

On shared machines, keep datasets, checkpoints, and outputs outside git. This keeps the repository clean for open source release, avoids accidental commits of generated media, and lets multiple benchmark runs reuse the same local asset roots:

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

Verify an existing machine before a run. This is useful after logging into a fresh shell, moving to another GPU node, or changing CUDA/PyTorch packages:

bash scripts/setup/bootstrap_worldfoundry.sh --verify-only
worldfoundry-eval --help

Detailed environment mapping by model and benchmark lives in Environment. Use that page when a model needs an extra conda profile or a benchmark evaluator depends on a metric package that is not part of the unified runtime.

2. Assets

WorldFoundry keeps executable code in tree. Checkpoints, datasets, metric weights, reference files, and generated outputs are staged locally, usually through Hugging Face. The important distinction is that missing assets are expected to be downloaded or mounted.

Model assets and benchmark assets are separate. A model checkpoint lets you generate candidate artifacts; benchmark assets define what to generate, how outputs should be named, and which files or metric weights are needed to compute scores.

For a model:

bash scripts/inference/prepare_model_infer.sh <model-id> --verify-env-only
bash scripts/inference/prepare_model_infer.sh <model-id> --download
worldfoundry-eval zoo model-download --model-id <model-id> --check-local --json

For a benchmark, start by asking WorldFoundry to print the asset plan. The plan shows the local paths, required environment variables, and the real evaluation command for that benchmark without downloading secrets or writing credentials:

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"

Use HF_TOKEN only for gated assets whose terms you have accepted. Public checkpoints and datasets should work without a token; gated Hugging Face assets still require accepting the upstream license first:

export HF_TOKEN=<your-huggingface-token>

Full cache and path conventions are in Local assets. If a command complains about a missing dataset, checkpoint, metric model, or generated output directory, that page explains where the file should live and which environment variable controls it.

3. TUI

Use the TUI when you do not want to remember ids and flags. It is the best first-run path because it reads the same model and benchmark manifests as the CLI, shows the available choices, and can print the final command before anything expensive runs.

python -m pip install -e ".[tui]"
worldfoundry-eval tui

Generate a command without entering the interactive session. This is useful when you want the TUI to resolve ids and defaults, but you still want to paste the command into a job script or terminal multiplexer:

worldfoundry-eval tui \
  --model-id <model-id> \
  --benchmark-id <benchmark-id> \
  --print-command

The TUI does not bypass missing checkpoint, dataset, license, or environment requirements. If it prints a command for a benchmark whose assets are not staged yet, run the benchmark asset preparation step first and then retry the generated command.

4. CLI

Use the CLI for scripts, batch jobs, and reproducible notes. Start with discovery commands instead of guessing ids: model ids, benchmark ids, and download declarations come from manifests, and the JSON output is easier to copy into automation.

Common discovery commands:

worldfoundry-eval zoo models --json
worldfoundry-eval zoo benchmarks --json
worldfoundry-eval zoo model-download --model-id <model-id> --check-local --json

Run model inference from the command line. The output directory is intentionally explicit because later evaluation commands need to know where generated videos, frames, trajectories, or result files were written:

python -m worldfoundry.studio.workspace_job infer \
  --model-id <model-id> \
  --prompt "a cinematic scene, high quality" \
  --output-dir tmp/worldfoundry_infer/<model-id> \
  --device cuda

For image-to-video or other conditioned models, pass an input file or directory along with the prompt and generation parameters. The exact supported flags depend on the selected model runner, so use this as the common shape and check the model page or TUI output for model-specific options:

python -m worldfoundry.studio.workspace_job infer \
  --model-id <model-id> \
  --input-path /path/to/input.png \
  --prompt "camera moves forward through the scene" \
  --frames 81 \
  --steps 30 \
  --seed 42 \
  --output-dir tmp/worldfoundry_infer/<model-id>

The full command map is in CLI. Use it as a reference after the main workflow is clear, not as the first page to read.

5. Inference

Inference produces artifacts. It does not produce benchmark evidence by itself. A generated video can look correct in Studio and still fail a benchmark run if the filenames, prompt coverage, split, or metadata do not match what the benchmark runner expects.

The practical loop is: generate a small batch, inspect the outputs, confirm the directory layout, and then scale to the full prompt set required by the target benchmark. This avoids spending GPU time on outputs that cannot be scored later.

For repeated visual review, start the workspace:

bash scripts/workspace/run_workspace.sh

Open:

http://127.0.0.1:7870/

Inspect the output directory or workspace gallery before scoring:

find tmp/worldfoundry_infer/<model-id> -maxdepth 2 -type f | head

More inference details are in Run inference and Studio. Use Studio for visual review and the filesystem path for evaluation handoff.

6. Evaluation

A benchmark run needs three concrete inputs. If any one is missing, the runner should stop with a blocked scorecard rather than silently producing a leaderboard-looking number.

If the official benchmark already produced a result file, import it. This path is for normalizing and recording official-shaped results inside WorldFoundry without rerunning the upstream evaluator:

worldfoundry-eval zoo benchmark-run \
  --benchmark-id <benchmark-id> \
  --mode official-validation \
  --official-results-path /path/to/official/results-or-report \
  --generated-artifact-dir /path/to/generated/artifacts \
  --output-dir tmp/<benchmark-id>/official-validation \
  --json

If generated artifacts are ready and the in-tree runner can compute metrics, run the integrated evaluator. This is the preferred path for benchmarks whose scoring code has been vendored and cleaned into WorldFoundry:

worldfoundry-eval zoo benchmark-run \
  --benchmark-id <benchmark-id> \
  --mode official-run \
  --generated-artifact-dir /path/to/generated/artifacts \
  --output-dir tmp/<benchmark-id>/official-run \
  --json

If a model-zoo model and benchmark-zoo runner support the one-cell path, WorldFoundry can launch the generation-and-scoring run from a single command. Use this only after assets and environment are known to be ready; otherwise it is harder to tell whether a failure came from generation or scoring:

worldfoundry-eval run \
  --benchmark <benchmark-id> \
  --model <model-id> \
  --mode official-run \
  --output-dir tmp/<benchmark-id>/<model-id> \
  --json

Open scorecard.json first. Public leaderboard claims require complete assets, complete generated artifacts, and the benchmark-specific eligibility flags. For debugging, also check the run manifest, per-sample results, and metric summaries written under the output directory.

Where Details Live

This page is intentionally the common path. Once you know which model or benchmark you are running, jump to the specific page below for exact data layout, metric checkpoints, simulator notes, and model-specific arguments.