Cosmos3 Setup

Source And Attribution

Adapted from NVIDIA cosmos-framework skills/atomic/cosmos3-setup/SKILL.md.

Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. Used under OpenMDW-1.1. See skills/LICENSE-NVIDIA-COSMOS3-OPENMDW-1.1 and skills/NOTICE-NVIDIA-COSMOS3.

When To Use

Use this skill when the task is about Cosmos3 first-run setup, source checkout, checkpoint access, credential verification, CUDA or uv install choices, or selecting the right NPA Cosmos3 workflow. If the user is already failing with an ImportError, CUDA error, Docker runtime error, or checkpoint download failure, switch to skills/atomic/cosmos3-env-troubleshoot/SKILL.md.

NPA Boundary

Cosmos3 skills are agent skills. Do not add or invoke Cosmos skill-display subcommands; those are intentionally not part of the NPA human CLI surface.

Real NPA setup surfaces are:

• npa workbench cosmos check for redacted source, Hugging Face, optional NGC, and parser-setting validation.
• npa workbench cosmos fetch for source plus checkpoint staging in a temporary runtime cache.
• workflows/testing/cosmos-fetch.yaml for a workflow fetch workflow that runs those real commands.
• workflows/testing/cosmos3-text-to-image.yaml for the H100 text-to-image smoke workflow.

Setup Flow

1. Inspect the NPA integration before changing behavior:

   rg -n "Cosmos3|cosmos3|NPA_COSMOS3" npa/src/npa npa/workflows npa/tests
   

2. Confirm access locally without downloading weights:

   npa/.venv/bin/npa workbench cosmos check --output json
   

   This command must redact model repo IDs, private source URLs, and token values in its output.

3. Stage source and checkpoint only when credentials are available:

   npa/.venv/bin/npa workbench cosmos fetch --output json
   

   Use --skip-checkpoint for source-only checks. Use --cache-dir for an ephemeral path, not a repository path.

4. For GPU inference, use the text-to-image SkyPilot workflow. The setup skill should point to that workflow; it should not create a skill launcher command.

5. Keep guardrails on by default. The only opt-out is an explicit user request mapped to NPA_COSMOS3_NO_GUARDRAILS=1 in the inference workflow.

Credential Inputs

Defaults are controlled by these environment variable names:

• NPA_COSMOS3_SOURCE_REPO, default https://github.com/NVIDIA/cosmos-framework.git
• NPA_COSMOS3_MODEL_ID, default nvidia/Cosmos3-Nano
• NPA_COSMOS3_CACHE, default /tmp/npa-cosmos3-cache
• NPA_COSMOS3_GITHUB_TOKEN_ENV, default GITHUB_TOKEN
• NPA_COSMOS3_HF_TOKEN_ENV, default HF_TOKEN
• NPA_COSMOS3_NGC_API_KEY_ENV, default NGC_API_KEY
• NPA_COSMOS3_REQUIRE_NGC, default 0

Never print token values. When diagnosing, report only whether each credential is configured, missing, skipped, or failed.

A read token is sufficient for downloads. For a fine-grained token, explicitly grant read access to every gated model and guardrail repo the selected path uses; accepting the repo terms on the account does not add that token scope.

Upstream Cosmos3 Notes

When an agent needs upstream package guidance, clone or inspect https://github.com/NVIDIA/cosmos-framework.git and read:

• docs/setup.md for system packages, uv groups, CUDA variants, and container setup.
• skills/atomic/cosmos3-setup/SKILL.md for NVIDIA's original setup guidance.
• skills/atomic/cosmos3-env-troubleshoot/SKILL.md for known error signatures.

Training extras use cu130-train or cu128-train. Inference-only groups omit training dependencies. Inside NGC PyTorch containers, clear LD_LIBRARY_PATH before Python imports if PyTorch reports internal import failures.