--- title: Quickstart description: Configure the environment, prepare assets, use the TUI or CLI, then run inference and evaluation. --- This guide walks through the shortest complete path from a clone to a reviewable WorldFoundry run: - [Environment](#1-environment) - [Assets](#2-assets) - [TUI](#3-tui) - [CLI](#4-cli) - [Inference](#5-inference) - [Evaluation](#6-evaluation) Most runs follow the same shape even when the model or benchmark changes: make the Python environment importable, discover stable IDs, prepare only the required checkpoints and benchmark assets, generate artifacts, inspect them, and only then score them. You do not need a GPU or model weights to browse catalogs and inspect readiness. Complete environment and discovery checks, read the reported blockers, and stop before asset download if you are only evaluating coverage. ## Workflow Create the conda environment and source WorldFoundry paths. Prepare only the model checkpoints, benchmark data, and metric assets needed for the run. Use the TUI when you want an interactive command builder, or use the CLI commands below when scripting. Run inference first. Run benchmark scoring only after generated artifacts match the benchmark layout. ## Prerequisites - **OS:** Linux recommended for GPU inference and most benchmark runners - **Install track:** use `python -m pip install -e ".[tui]"` for lightweight CPU catalog/CLI/TUI work; use `bash scripts/setup/bootstrap_worldfoundry.sh` for the CUDA conda runtime. That bootstrap is the official first-clone script; it already calls `scripts/setup/unified_install.sh` to create the unified GPU env, so you do not start from `unified_install.sh` unless you are only refreshing that env. Optional extras do not select a CUDA PyTorch wheel index. - **Python:** 3.10+; the GPU path manages it through the WorldFoundry unified conda environment - **Optional:** CUDA-capable GPU, Hugging Face token for gated checkpoints Catalog browsing and readiness inspection work without weights. The expensive path begins only when you choose a concrete model run and download assets. ## 1. Environment The commands below describe the GPU runtime path. The official first-clone command is `bash scripts/setup/bootstrap_worldfoundry.sh`. It 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. Start from the repository root. Model demo videos are served from GitHub CDN; docs development does not need `git lfs pull`. ```bash GIT_LFS_SKIP_SMUDGE=1 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: ```bash 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: ```bash bash scripts/setup/bootstrap_worldfoundry.sh --verify-only worldfoundry-eval --help ``` Detailed environment mapping by model and benchmark lives in [Environment](/docs/reference/environments). Use that page when a model needs an extra conda profile or a benchmark evaluator depends on a metric package outside 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. 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. ```bash bash scripts/inference/prepare_model_infer.sh --verify-env-only bash scripts/inference/prepare_model_infer.sh --download worldfoundry-eval zoo model-download --model-id --check-local --json ``` Start by asking WorldFoundry to print the asset plan: ```bash python scripts/setup/prepare_benchmark_assets.py \ --benchmark-id \ --json python scripts/setup/prepare_benchmark_assets.py \ --benchmark-id \ --write-env "${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}/.env" \ --create-dirs source "${WORLDFOUNDRY_HOME:-${HOME}/.cache/worldfoundry}/.env" ``` Use `HF_TOKEN` only for gated assets whose terms you have accepted: ```bash export HF_TOKEN= ``` Full cache and path conventions are in [Local assets](/docs/guides/local-assets). ## 3. TUI Use the TUI when you do not want to remember IDs and flags. It reads the same manifests as the CLI, shows the available choices, and can print the final command before anything expensive runs. ```bash python -m pip install -e ".[tui]" worldfoundry-eval tui ``` Generate a command without entering the interactive session: ```bash worldfoundry-eval tui \ --model-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. ## 4. CLI Use the CLI for scripts, batch jobs, and reproducible notes. Start with the discovery commands instead of guessing IDs: ```bash worldfoundry-eval zoo models --json worldfoundry-eval zoo benchmarks --json worldfoundry-eval zoo model-download --model-id --check-local --json ``` The canonical first inference command for reproducible and documented runs is `worldfoundry-eval run --pipeline.task-profile …`. Copy `` and the task profile from the model page; `worldfoundry-eval run --help` lists the typed flags. ```bash worldfoundry-eval run \ --pipeline.task-profile \ --output-dir tmp/worldfoundry_infer/ ``` **Which command.** Everyday reproducible runs and the commands on model pages use `worldfoundry-eval run`. Use `python -m worldfoundry.studio.workspace_job infer` only for Workspace visual smoke. See [CLI entrypoints](/docs/reference/cli#entrypoints). Workspace visual smoke (the same job path the Studio UI submits): ```bash python -m worldfoundry.studio.workspace_job infer \ --model-id \ --prompt "a cinematic scene, high quality" \ --output-dir tmp/worldfoundry_infer/ \ --device cuda ``` The full command map is in [CLI](/docs/reference/cli). Run-status labels are in [Run status](/docs/guides/run-status). ## 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 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. For repeated visual review, start the workspace: ```bash bash scripts/workspace/run_workspace.sh ``` Open `http://127.0.0.1:7870/` and inspect outputs before scoring: ```bash find tmp/worldfoundry_infer/ -maxdepth 2 -type f | head ``` More details: [Run inference](/docs/guides/inference) and [Studio](/docs/guides/studio). ## 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. - **Benchmark assets** — Prompt/task metadata, reference files, official result files, judge credentials, simulator assets, or metric checkpoints. - **Candidate artifacts** — Videos, frames, rollouts, traces, or official-shaped result dumps produced by the model. - **Runner mode** — `official-validation` imports existing official-shaped results; `official-run` computes scores from generated artifacts. If the official benchmark already produced a result file, import it: ```bash worldfoundry-eval zoo benchmark-run \ --benchmark-id \ --mode official-validation \ --official-results-path /path/to/official/results-or-report \ --generated-artifact-dir /path/to/generated/artifacts \ --output-dir tmp//official-validation \ --json ``` If generated artifacts are ready and the in-tree runner can compute metrics: ```bash worldfoundry-eval zoo benchmark-run \ --benchmark-id \ --mode official-run \ --generated-artifact-dir /path/to/generated/artifacts \ --output-dir tmp//official-run \ --json ``` If model-zoo and benchmark-zoo support the one-cell path: ```bash worldfoundry-eval run \ --benchmark \ --model \ --mode official-run \ --output-dir tmp// \ --json ``` Open `scorecard.json` first. Public leaderboard claims require complete assets, complete generated artifacts, and benchmark-specific eligibility flags. ## Where details live