Skip to navigation
ReferenceProjects and Environments

AI Workbench Projects Reference

View as Markdown

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.

RuleDescription
UniquenessMust be unique within a location.
CharactersLetters, numbers, hyphens, and underscores. No spaces or special characters.
RenamingRequires 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 FolderDescription
.project/spec.yamlRequired. Core configuration file managed by AI Workbench and tracked by Git. Defines project metadata, environment, and applications. See AI Workbench Project Specification.
.project/configpacksRequired but created automatically. Managed by AI Workbench and tracked by Git. Tracks when configpacks are run to avoid duplication.
apt.txtOptional. Lists Debian packages to install during container build. One package per line. See Manage Packages.
requirements.txtOptional. Lists Python packages to install during container build. Standard pip requirements format. See Manage Packages.
preBuild.bashOptional. Bash script executed before package installation during container build. Runs as the container user with passwordless sudo. See Use the preBuild.bash Script.
postBuild.bashOptional. Bash script executed after package installation during container build. Runs as the container user with passwordless sudo. See Use the postBuild.bash Script.
onStart.bashOptional. Project-root bash script executed as the project user each time the project container starts. Passwordless sudo is available while the script runs. See Use the onStart.bash Script.
variables.envOptional. 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.

FieldDescription
nameProject name.
pathAbsolute path to the project directory on the host.
locationThe location where the project is registered (e.g., local).
last_openedISO 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

TopicDescription
AI Workbench Project SpecificationComplete .project/spec.yaml field reference.
Single Container EnvironmentsNVIDIA default base images for project creation.
Runtime Configuration (Environment Variables and Mounts)Mounts and environment variable specifications.
GPU ConfigurationGPU allocation and shared memory configuration.
Single Container EnvironmentsCustom container label specification (on the Single Container Environments page).
Multi-Container Environments (Docker Compose)Docker Compose multi-container environment specifications.
Docker Compose Pattern ExamplesCommon multi-container Compose patterns and examples.