> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/ai-workbench/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/ai-workbench/_mcp/server.

# AI Workbench Projects Reference

**This page documents the technical specifications for AI Workbench projects.**

For conceptual background, see [AI Workbench Projects](/ai-workbench/concepts/project-concept).
For step-by-step procedures, see [How to Work with AI Workbench Projects](/ai-workbench/how-to/projects/overview).

## 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](/ai-workbench/reference/projects/spec). |
| `.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](/ai-workbench/how-to/environments/package-management). |
| `requirements.txt` | Optional. Lists Python packages to install during container build. Standard pip requirements format. See [Manage Packages](/ai-workbench/how-to/environments/package-management). |
| `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](/ai-workbench/how-to/environments/prebuild-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](/ai-workbench/how-to/environments/postbuild-script). |
| `onStart.bash` | Optional. 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](/ai-workbench/how-to/environments/onstart-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](/ai-workbench/reference/projects/spec) | Complete `.project/spec.yaml` field reference. |
| [Single Container Environments](/ai-workbench/reference/projects/base-environments) | NVIDIA default base images for project creation. |
| [Runtime Configuration (Environment Variables and Mounts)](/ai-workbench/reference/projects/runtime-configuration-reference) | Mounts and environment variable specifications. |
| [GPU Configuration](/ai-workbench/reference/projects/hardware-reference) | GPU allocation and shared memory configuration. |
| [Single Container Environments](/ai-workbench/reference/projects/base-environments) | Custom container label specification (on the Single Container Environments page). |
| [Multi-Container Environments (Docker Compose)](/ai-workbench/reference/projects/compose-reference) | Docker Compose multi-container environment specifications. |
| [Docker Compose Pattern Examples](/ai-workbench/reference/projects/compose-patterns-reference) | Common multi-container Compose patterns and examples. |

## Related Topics

- [AI Workbench Projects](/ai-workbench/concepts/project-concept) - Conceptual overview of projects
- [How to Work with AI Workbench Projects](/ai-workbench/how-to/projects/overview) - How-to procedures for working with projects
- [Create, Clone, Publish and Delete Projects](/ai-workbench/how-to/projects/create-clone-publish) - How to create, clone, publish, and delete projects
- [Git Configuration Reference](/ai-workbench/reference/git-configuration-reference) - Git integration and versioning details