AI Workbench Projects Reference#

This page documents the technical specifications for AI Workbench projects.: For conceptual background, see AI Workbench Projects. For step-by-step procedures, see How to Work with AI Workbench Projects.

Project Naming#

The project name and the directory name on disk are different things.: The project name is defined in .project/spec.yaml under meta.name. AI Workbench uses the project name for container naming, runtime folder paths, and display in the UI. The directory name on disk depends on how the project was obtained.
When you create a project locally, the directory name matches the project name.: When you clone a project from another user’s namespace, the directory name includes the namespace prefix (e.g., nvidia_my-project). When you clone a project from your own namespace, the directory name does not include the namespace. In all cases, meta.name in spec.yaml contains only the project name without any namespace.

Rule	Description
Uniqueness	Must be unique within a location.
Characters	Letters, numbers, hyphens, and underscores. No spaces or special characters.
Renaming	Requires editing `spec.yaml` and may require rebuilding the container.

Project Structure#

AI Workbench relies on configuration files to manage the repository and containerized runtime.: Configuration files are managed by AI Workbench and tracked by Git. Users can manually edit them.

File or Folder	Description
`.project/spec.yaml`	Required. Core configuration file managed by AI Workbench and tracked by Git. Defines project metadata, environment, and applications. See AI Workbench Project Specification.
`.project/configpacks`	Required but created automatically. Managed by AI Workbench and tracked by Git. Tracks when configpacks are run to avoid duplication.
`apt.txt`	Optional. Lists Debian packages to install during container build. One package per line. See Manage Packages.
`requirements.txt`	Optional. Lists Python packages to install during container build. Standard pip requirements format. See Manage Packages.
`preBuild.bash`	Optional. Bash script executed before package installation during container build. Runs as the container user with passwordless sudo. See Use the preBuild.bash Script.
`postBuild.bash`	Optional. Bash script executed after package installation during container build. Runs as the container user with passwordless sudo. See Use the postBuild.bash Script.
`variables.env`	Optional. Non-sensitive environment variables set in the container at runtime. Variables are not built into the container image. Tracked by Git.

Project Registration#

AI Workbench tracks projects through a host specific inventory file and a runtime metadata folder.: Projects created or cloned outside of AI Workbench (e.g., with git clone) are not registered and cannot be opened. Always use AI Workbench to create or clone projects.

Inventory File#

The inventory file is located at $HOME/.nvwb/inventory.json.

Field	Description
name	Project name.
path	Absolute path to the project directory on the host.
location	The location where the project is registered (e.g., `local`).
last_opened	ISO 8601 timestamp of when the project was last opened.

Runtime Metadata Folder#

AI Workbench creates a runtime folder for each project at $HOME/.nvwb/runtime/<PROJECT-NAME>/.

This folder stores container state information, local configuration overrides, application runtime data, and build cache metadata. It is not part of the Git repository and does not sync across locations.

Additional Project Reference Topics#

Topic	Description
AI Workbench Project Specification	Complete `.project/spec.yaml` field reference.
Single Container Environments	NVIDIA default base images for project creation.
Runtime Configuration (Environment Variables and Mounts)	Mounts and environment variable specifications.
GPU Configuration	GPU allocation and shared memory configuration.
Single Container Environments	Custom container label specification (on the Single Container Environments page).
Multi-Container Environments (Docker Compose)	Docker Compose multi-container environment specifications.
Docker Compose Pattern Examples	Common multi-container Compose patterns and examples.