NVIDIA AI Workbench — Local Machine (Control Plane)

NVIDIA AI Workbench is a lightweight, containerized development platform for GPU-accelerated AI/ML workflows. Every project is a Git repo with a .project/spec.yaml that defines the container environment. It supports Docker and Podman as container runtimes.

The nvwb CLI always runs on the local machine — the user's laptop or desktop. From there it manages contexts, which may be local (container on the same machine) or remote (container on a server or cloud instance accessed via SSH). Codex using this skill is on the local machine.

The user wants help with: $ARGUMENTS

Core Concepts

• Contexts — Locations/machines where projects run (local, remote SSH, Brev cloud)
• Projects — Git repos with container configuration (.project/spec.yaml)
• Applications — Services inside the container (JupyterLab, VS Code, custom webapps/processes)
• Environment Variables — Runtime values set via CLI; sensitive ones (--is-sensitive) are masked in output. Values are never committed to Git. Projects may declare required secret variable names in spec.yaml under execution.secrets.

Current State Detection

Before taking action, check the current state:

nvwb list contexts        # What locations are configured?
nvwb status               # Is a project open? Is the container running?
nvwb list projects        # What projects exist in the active context?

Build vs Runtime Isolation

Build-time (changes require nvwb build):

• apt.txt — system packages
• requirements.txt — pip packages
• preBuild.bash / postBuild.bash — custom build scripts
• Package manager entries in spec.yaml

Runtime (changes require container restart: nvwb close + nvwb open):

• variables.env — environment variables
• Mount configuration changes
• App definitions in spec.yaml

No action needed:

• Code in layout directories (code/, data/, models/) — live-mounted at /project/

Key Environment Variables

Variable	Available	Description
$NVWB_UID	Build-time	User ID for file ownership in build scripts
$NVWB_GID	Build-time	Group ID for file ownership in build scripts
$PROXY_PREFIX	Runtime	URL prefix for proxied web apps

Error Handling

When a build fails:

1. Read the build output carefully for the error message
2. Common causes: bad package version in requirements.txt, missing apt dependency, bash syntax error in build scripts
3. For deeper logs, check project-runtime-info/ inside the context's workbench directory — this is on the machine running the Workbench service, not necessarily the local machine. Find the right path first:

   cat ~/.nvwb/contexts.json   # workbenchDir field for each context
   

   • Local context: ~/.nvwb/project-runtime-info/
   • Remote context (SSH or Brev): <workbenchDir>/project-runtime-info/ on the remote — access via ssh <context-name> "ls <workbenchDir>/project-runtime-info/"
4. Fix the relevant config file
5. Run nvwb build again
6. For persistent issues, try nvwb build --full-build for a clean rebuild

When to Rebuild vs Restart vs Do Nothing

Change	Action
Edit code files	Nothing
Edit apt.txt, requirements.txt, build scripts	nvwb build
Edit variables.env	nvwb close then nvwb open
Change mounts or app config in spec.yaml	nvwb close then nvwb open
Change compose services	nvwb compose down then nvwb compose up

References

See the reference files for detailed information:

• references/cli-reference.md — Complete CLI command reference
• references/spec-reference.md — spec.yaml structure and fields
• references/project-structure.md — Project file layout and roles
• references/workflows.md — Multi-step workflow recipes
• references/nvwb-brev.md — Brev cloud GPU integration: stoppability, interactive vs manual bootstrap, org management, Brev CLI reference
• references/codex-in-container.md — Running Codex inside the container, credential persistence, and the host↔container bridge pattern