> 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 Project Specification

## Example AI Workbench Project Spec File

The following is an example of an AI Workbench project *spec.yaml* file.

```yaml
specVersion: v2
specMinorVersion: 1
meta:
  name: example-project
  image: project-example-project
  description: An example project using PyTorch
  labels: []
  createdOn: "2024-01-04T23:32:17Z"
  defaultBranch: main
layout:
- path: code/
  type: code
  storage: git
- path: models/
  type: models
  storage: gitlfs
- path: data/
  type: data
  storage: gitlfs
- path: data/scratch/
  type: data
  storage: gitignore
environment:
  base:
    registry: nvcr.io
    image: nvidia/ai-workbench/pytorch:1.0.2
    build_timestamp: "20231212000523"
    name: PyTorch
    supported_architectures: []
    cuda_version: "12.2"
    description: A Pytorch 2.1 environment with CUDA 12.2
    entrypoint_script: ""
    labels:
    - cuda12.2
    - pytorch2.1
    apps:
    - name: jupyterlab
      type: jupyterlab
      class: webapp
      start_command: jupyter lab --allow-root --port 8888 --ip 0.0.0.0 --no-browser
        --NotebookApp.base_url=\$PROXY_PREFIX --NotebookApp.default_url=/lab --NotebookApp.allow_origin='*'
      health_check_command: '[ \$(echo url=\$(jupyter lab list | head -n 2 | tail
        -n 1 | cut -f1 -d'' '' | grep -v ''Currently'' | sed "s@/?@/lab?@g") | curl
        -o /dev/null -s -w ''%{http_code}'' --config -) == ''200'' ]'
      timeout_seconds: 90
      stop_command: jupyter lab stop 8888
      user_msg: ""
      icon_url: ""
      webapp_options:
        autolaunch: true
        port: "8888"
        proxy:
          trim_prefix: false
        url_command: jupyter lab list | head -n 2 | tail -n 1 | cut -f1 -d' ' | grep
          -v 'Currently'
    - name: tensorboard
      type: tensorboard
      class: webapp
      start_command: tensorboard --logdir \$TENSORBOARD_LOGS_DIRECTORY --path_prefix=\$PROXY_PREFIX
        --bind_all
      health_check_command: '[ \$(curl -o /dev/null -s -w ''%{http_code}'' http://localhost:\$TENSORBOARD_PORT\$PROXY_PREFIX/)
        == ''200'' ]'
      timeout_seconds: 90
      stop_command: ""
      user_msg: ""
      icon_url: ""
      webapp_options:
        autolaunch: true
        port: "6006"
        proxy:
          trim_prefix: false
        url: http://localhost:6006
    programming_languages:
    - python3
    icon_url: ""
    image_version: 1.0.3
    os: linux
    os_distro: ubuntu
    os_distro_release: "22.04"
    schema_version: v2
    user_info:
      uid: "1001"
      gid: "1001"
      username: "appuser"
    package_managers:
    - name: apt
      binary_path: /usr/bin/apt
      installed_packages:
      - curl
      - git
      - git-lfs
      - vim
    - name: pip
      binary_path: /usr/local/bin/pip
      installed_packages:
      - jupyterlab==4.0.7
    package_manager_environment:
      name: ""
      target: ""
execution:
  apps: []
  resources:
    gpu:
      requested: 1
      sharedMemoryMB: 1024
  secrets: []
  mounts:
  - type: project
    target: /project/
    description: project directory
    options: rw
  - type: volume
    target: /data/tensorboard/logs/
    description: Tensorboard Log Files
    options: volumeName=tensorboard-logs-volume
```

## AI Workbench Project Spec Definition

### Project Metadata

The spec file includes project metadata, such as version, name, description, and directory structure.
The project spec file contains the following metadata fields:

<table>
<thead>
<tr>
<th>

**Field**

</th>
<th>

**Description**

</th>
<th>

**Example Usage**

</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`specVersion`

</td>
<td>

Specifies the schema version number of the current project specification file.

</td>
<td>

```yaml
specVersion: v2
```

</td>
</tr>
<tr>
<td>

`specMinorVersion`

</td>
<td>

Specifies the schema minor version number of the current project specification file.

</td>
<td>

```yaml
specMinorVersion: 1
```

</td>
</tr>
<tr>
<td>

`meta`

</td>
<td>

Specifies the metadata for the project to appear correctly in the AI Workbench application.

</td>
<td>

—

</td>
</tr>
<tr>
<td>

`meta.name`

</td>
<td>

Specifies the name of the project.

</td>
<td>

```yaml
name: hello-world
```

</td>
</tr>
<tr>
<td>

`meta.image`

</td>
<td>

Specifies the name of the project container image. This image name is local to the computer and isn't pushed to a container registry.

</td>
<td>

```yaml
image: project-hello-world
```

</td>
</tr>
<tr>
<td>

`meta.description`

</td>
<td>

Specifies the description of the project.

</td>
<td>

```yaml
description: An example project using PyTorch
```

</td>
</tr>
<tr>
<td>

`meta.labels`

</td>
<td>

Specifies a list of labels for the project.

</td>
<td>

—

</td>
</tr>
<tr>
<td>

`meta.createdOn`

</td>
<td>

Specifies when the project was created, formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.txt) string.

</td>
<td>

```yaml
createdOn: "2024-01-04T23:32:17Z"
```

</td>
</tr>
<tr>
<td>

`meta.defaultBranch`

</td>
<td>

Specifies the default Git branch for the project.

</td>
<td>

```yaml
defaultBranch: main
```

</td>
</tr>
<tr>
<td>

`layout`

</td>
<td>

Specifies a list of information about the project directories. AI Workbench uses this information to reconcile configuration. For instance, if a path was added to the .gitignore or .gitattributes files.

- `path` is a project directory relative to the root of the repository.
- `type` is the type of content in the directory. Valid values are `code`, `data`, and `model`.
- `storage` is how the data in the directory should be stored. Valid values are `git`, `gitlfs`, and `gitignore`.

</td>
<td>

```yaml
layout:
  - path: data/scratch/
    type: data
    storage: gitignore
```

</td>
</tr>
</tbody>
</table>

### Project Environment Information

The specification file includes environment information, such as the container image for the project, and additional packages that are installed in it.
You can manually configure this section of the spec, but typically it is populated automatically from the labels of the environment image that you select when you create a project.

<Warning>

Any manual modifications to the data in the `environment.base` section of the *spec.yaml* file are overridden when the environment version is updated.

</Warning>

In the `environment` section of the specification file, all fields are children of the `base` field.

```yaml
environment:
  base:
    ... all fields
```

The `environment.base` section contains the following fields.

<table>
<thead>
<tr>
<th>

**Field**

</th>
<th>

**Description**

</th>
<th>

**Example Usage**

</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`registry`

</td>
<td>

Specifies the container registry that has the image.

</td>
<td>

```yaml
registry: nvcr.io
```

</td>
</tr>
<tr>
<td>

`image`

</td>
<td>

Specifies the container image on top of which the project container is built.

</td>
<td>

```yaml
image: nvidia/pytorch:23.12-py3
```

</td>
</tr>
<tr>
<td>

`build_timestamp`

</td>
<td>

Specifies the timestamp of the last image build. The timestamp is formatted in year, month, day, hour, minutes, and seconds.

</td>
<td>

```yaml
build_timestamp: "20231212000523"
```

</td>
</tr>
<tr>
<td>

`name`

</td>
<td>

Specifies the name of the container.

</td>
<td>

```yaml
name: PyTorch
```

</td>
</tr>
<tr>
<td>

`supported_architectures`

</td>
<td>

Specifies a list of supported architectures that the image is compatible with.

</td>
<td>

```yaml
supported_architectures:

  - "amd64"
  - "arm64"
```

</td>
</tr>
<tr>
<td>

`cuda_version`

</td>
<td>

Specifies the version of the CUDA installed in the environment, if applicable. This field tells AI Workbench what version of the CUDA the host driver must support. If this value is not set correctly, you may experience runtime errors that AI Workbench fails to warn you about when starting the container.

</td>
<td>

```yaml
cuda_version: "12.2"
```

</td>
</tr>
<tr>
<td>

`description`

</td>
<td>

Specifies the description of the container.

</td>
<td>

```yaml
description: A Pytorch 2.1 environment with CUDA 12.2
```

</td>
</tr>
<tr>
<td>

`entrypoint_script`

</td>
<td>

Specifies the path to the base-image entrypoint script that AI Workbench preserves and runs before the project `onStart.bash` script. See [Use the onStart.bash Script](/ai-workbench/how-to/environments/onstart-script).

</td>
<td>

```yaml
entrypoint_script: /path/to/script.sh
```

</td>
</tr>
<tr>
<td>

`labels`

</td>
<td>

Specifies a list of labels for the container, such as search term keywords or descriptors.

</td>
<td>

```yaml
labels:
  - cuda12.2
  - pytorch2.1
  - python3
  - jupyterlab
```

</td>
</tr>
<tr>
<td>

`apps`

</td>
<td>

Specifies a list of applications installed in the container. For the definition of the fields in `apps`, see [Project App Information](/ai-workbench/reference/projects/spec#project-app-information).

</td>
<td>

```yaml
apps:
- name: jupyterlab
  ... more fields
- name: tensorboard
  ... more fields
```

</td>
</tr>
<tr>
<td>

`programming_languages`

</td>
<td>

Specifies the list of programming languages installed in the container.

</td>
<td>

```yaml
programming_languages:
  - python3
```

</td>
</tr>
<tr>
<td>

`icon_url`

</td>
<td>

Specifies the link to the icon or image that is associated with the container.

</td>
<td>

```yaml
icon_url: https://my-website.com/my-image.png
```

</td>
</tr>
<tr>
<td>

`image_version`

</td>
<td>

Specifies the version number of the container image, if any exist.

</td>
<td>

```yaml
image_version: 1.0.3
```

</td>
</tr>
<tr>
<td>

`os`

</td>
<td>

Specifies the name of the container's operating system.

</td>
<td>

```yaml
os: linux
```

</td>
</tr>
<tr>
<td>

`os_distro`

</td>
<td>

Specifies the name of the container operating system's distribution.

</td>
<td>

```yaml
os_distro: ubuntu
```

</td>
</tr>
<tr>
<td>

`os_distro_release`

</td>
<td>

Specifoes the release version of the container operating system's distribution.

</td>
<td>

```yaml
os_distro_release: "22.04"
```

</td>
</tr>
<tr>
<td>

`schema_version`

</td>
<td>

Specifies the metadata for the version of the container label schema currently read by AI Workbench.

</td>
<td>

```yaml
schema_version: v2
```

</td>
</tr>
<tr>
<td>

`user_info`

</td>
<td>

Specifies information about the user that the container processes should run as.

</td>
<td>

```yaml
user_info:
  uid: "1001"
  gid: "1001"
  username: "appuser"
```

</td>
</tr>
<tr>
<td>

`package_managers`

</td>
<td>

Specifies a list of package managers installed in the container, and for each one an optional list of installed packages.

</td>
<td>

```yaml
package_managers:
- name: conda
  binary_path: /opt/conda/bin/conda
  installed_packages:
  - python=3.9.18
  - pip
- name: apt
  binary_path: /usr/bin/apt
  installed_packages:
  - ca-certificates
  - curl
- name: pip
  binary_path: /opt/conda/bin/pip
  installed_packages: []
```

</td>
</tr>
<tr>
<td>

`package_manager_environment`

</td>
<td>

Specifies a package manager environment that should be activated before installing packages and starting applications. This field is useful if your container uses a virtual environment or Conda when building.

</td>
<td>

```yaml
package_manager_environment:
  name: ""
  target: ""
```

</td>
</tr>
</tbody>
</table>

### Project App Information

The specification file includes information about applications installed in the environment. This includes custom applications, such as commands and parameters for running them.

The Project App section contains the following fields:

<table>
<thead>
<tr>
<th>

**Field**

</th>
<th>

**Description**

</th>
<th>

**Example Usage**

</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`name`

</td>
<td>

Specifies the name of the application. This name appears in the user interface.

</td>
<td>

```yaml
name: jupyterlab
```

</td>
</tr>
<tr>
<td>

`type`

</td>
<td>

Specifies the type of application, used to determine what application-specific automation is run.

</td>
<td>

```yaml
type: jupyterlab
```

</td>
</tr>
<tr>
<td>

`class`

</td>
<td>

Specifies the class of application, used to determine what optional configuration options are available. Valid values are `webapp`, `process`, and `native`.

</td>
<td>

```yaml
class: webapp
```

</td>
</tr>
<tr>
<td>

`start_command`

</td>
<td>

Specifies the shell command used to start the application. Must not be a blocking command.

</td>
<td>

```yaml
start_command: jupyter lab...
```

</td>
</tr>
<tr>
<td>

`health_check_command`

</td>
<td>

Specifies the shell command used to check the health or status of the application. A return of zero means the application is running and healthy. A return of non-zero means that the application is not running or unhealthy.

</td>
<td>

```yaml
health_check_command: '<code>'
```

</td>
</tr>
<tr>
<td>

`timeout_seconds`

</td>
<td>

Specifies the number of seconds that AI Workbench waits for the `health_check_command` to complete. Valid values are greater than 0 and less than 3600. The default value is 60.

</td>
<td>

```yaml
timeout_seconds: 90
```

</td>
</tr>
<tr>
<td>

`stop_command`

</td>
<td>

The shell command used to stop the application.

</td>
<td>

```yaml
stop_command: jupyter lab stop 8888
```

</td>
</tr>
<tr>
<td>

`user_msg`

</td>
<td>

An optional message that appears to the user when the application is running. If `class` is `webapp`, you can use the placeholder string `{{URL}}` in the message, and it is populated after the app starts.

</td>
<td>

```yaml
user_msg: ""
```

</td>
</tr>
<tr>
<td>

`icon_url`

</td>
<td>

Specifies a link to the icon or image used for the application. This field is optional.

</td>
<td>

```yaml
icon_url: ""
```

</td>
</tr>
<tr>
<td>

`webapp_options`

</td>
<td>

If `class` is `webapp`, the following options are available:

- `autolaunch` - `true` if AI Workbench should automatically open the application URL for the user; otherwise, `false`.
- `port` - The port that the application runs on.
- `proxy` - If this field is specified, include `trim_prefix` - `true` if the AI Workbench reverse proxy should remove the application-specific Url prefix before forwarding the request to the application; otherwise, `false`.
- `url` - The static URI used to access the application.
- Or `url_command` - The shell command used to get the URI for the application. The output from this command is considered the URL.

If `class` is `process`, the following options are available:

- `wait_until_finished` - `true` if the AI Workbench Desktop Application should wait for the application to finish; `false` if the desktop app should let it run in the background. If `true` the desktop app notifies you when the process completes. The CLI always waits.

</td>
<td>

```yaml
webapp_options:
  autolaunch: true
  port: "8888"
  proxy:
    trim_prefix: false
  url_command: <your command>
```
```yaml
webapp_options:
  autolaunch: true
  port: "6006"
  proxy:
    trim_prefix: false
  url: http://localhost:6006
```
```yaml
process_options:
  wait_until_finished: true
```

</td>
</tr>
</tbody>
</table>

Project Runtime Information
----------------------------\`\`

The specification file includes runtime information, such as environment variables, the number of GPUs to be mounted in the container, and custom application information.

The Project Runtime Information section contains the following fields:

<table>
<thead>
<tr>
<th>

**Field**

</th>
<th>

**Description**

</th>
<th>

**Example Usage**

</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`execution`

</td>
<td>

Specifies information about how to run the project.

</td>
<td>

—

</td>
</tr>
<tr>
<td>

`execution.apps`

</td>
<td>

Specifies a list of custom applications installed in the project that are not part of the container environment. For the definition of the fields in `apps`, see [Project App Information](/ai-workbench/reference/projects/spec#project-app-information).

</td>
<td>

```yaml
apps:
- name: jupyterlab
  ... more fields
- name: mychat
  ... more fields
```

</td>
</tr>
<tr>
<td>

`execution.resources`

</td>
<td>

Specifies host resources that are requested or required to run the project.

- `gpu` is the number of GPUs requested. If no GPUs are available the project can be started without any GPUs.
- `sharedMemoryMB` is the amount of shared memory (in MB) to allocate to the project container.

For more information, see [GPU Configuration](/ai-workbench/reference/projects/hardware-reference).

</td>
<td>

```yaml
resources:
  gpu:
    requested: 0
  sharedMemoryMB: 0
```

</td>
</tr>
<tr>
<td>

`execution.secrets`

</td>
<td>

Specifies a list of sensitive environment variables to set before the project starts. Only specify the name and description of each variable. The value of each variable is not part of the specification file and is configured at runtime.

</td>
<td>

```yaml
secrets:
- variable: secret1
  description: Secret 1
```

</td>
</tr>
<tr>
<td>

`execution.mounts`

</td>
<td>

Specifies a list of external folders and files that are used by the project, and where they should be located in the project container. The required values to configure the mount (like the source directory) are not part of the specification file, and are configured at runtime.

- For `type`, valid values are `project`, `host`, `volume`, or `tmp`. There is exacly one `project` mount (or the container fails to start).
- `target` is the target location within the project container. Target locations are absolute paths and include the trailing slash.

For more information, see [Runtime Configuration (Environment Variables and Mounts)](/ai-workbench/reference/projects/runtime-configuration-reference).

</td>
<td>

```yaml
mounts:
  - type: project
    target: /project/
    description: project directory
    options: rw
```

</td>
</tr>
</tbody>
</table>

## Container Specification

To view the full description and example usage for each field, see [AI Workbench Project Spec Definition](/ai-workbench/reference/projects/spec#ai-workbench-project-spec-definition).

The specification file contains the following fields:

<table>
<thead>
<tr>
<th>

**Field**

</th>
<th>

**Change?**

</th>
<th>

**Recommended Action**

</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`registry`

</td>
<td>

Required

</td>
<td>

Specify the container registry for your container of interest; if you have the Dockerfile, you may need to first build the container and push it to a registry.

</td>
</tr>
<tr>
<td>

`image`

</td>
<td>

Required

</td>
<td>

Specify the container image (and tag, if any) for your container of interest; if you have the Dockerfile, you may need to first build the container and push it to a registry. Also include the namespace if needed, but do not include the registry.

</td>
</tr>
<tr>
<td>

`build_timestamp`

</td>
<td>

Optional

</td>
<td>

No manual updates are necessary. AI Workbench automatically updates this field when you build your environment.

</td>
</tr>
<tr>
<td>

`name`

</td>
<td>

Required

</td>
<td>

Specify the name for the container. AI Workbench will display the old container information in the UI if this setting isleft unchanged.

</td>
</tr>
<tr>
<td>

`supported_architectures`

</td>
<td>

Recommended

</td>
<td>

Specify the list of supported architectures for your container. You can leave this blank if not applicable.

</td>
</tr>
<tr>
<td>

`cuda_version`

</td>
<td>

Required

</td>
<td>

Specify the version of CUDA installed in this container. If this isn't applicable, you can leave this blank. AI Workbench matches drivers incorrectly if this is not updated.

</td>
</tr>
<tr>
<td>

`description`

</td>
<td>

Required

</td>
<td>

Specify a brief and informative description of the container. AI Workbench displays the old container information in the UI if left unchanged.

</td>
</tr>
<tr>
<td>

`entrypoint_script`

</td>
<td>

Optional

</td>
<td>

Specify the path to the base-image entrypoint script that AI Workbench must preserve. AI Workbench runs this script before the project-root `onStart.bash` script. Use [Use the onStart.bash Script](/ai-workbench/how-to/environments/onstart-script) for project-specific startup actions.

</td>
</tr>
<tr>
<td>

`labels`

</td>
<td>

Recommended

</td>
<td>

Specify a list of search term keywords or labels to you want attached alongside your container. Consider these as search term keywords or descriptors for your container.

</td>
</tr>
<tr>
<td>

`apps`

</td>
<td>

Recommended

</td>
<td>

Specify the applications that you are installing with in the container. For details, see [Project App Information](/ai-workbench/reference/projects/spec#project-app-information).

</td>
</tr>
<tr>
<td>

`programming_languages`

</td>
<td>

Recommended

</td>
<td>

Specify the programming languages that you are installing with this container, or leave blank if not applicable.

</td>
</tr>
<tr>
<td>

`icon_url`

</td>
<td>

Optional

</td>
<td>

If you would like AI Workbench to display an icon as part of this container, link the URL to the icon image here or leave it blank for defaults.

</td>
</tr>
<tr>
<td>

`image_version`

</td>
<td>

Recommended

</td>
<td>

Specify the version number of the container image, if any.

</td>
</tr>
<tr>
<td>

`os`

</td>
<td>

Recommended

</td>
<td>

Specify the name of the container operating system.

</td>
</tr>
<tr>
<td>

`os_distro`

</td>
<td>

Recommended

</td>
<td>

Specify the name of the container operating system distribution.

</td>
</tr>
<tr>
<td>

`os_distro_release`

</td>
<td>

Recommended

</td>
<td>

Specify the release version of the container operating system distribution.

</td>
</tr>
<tr>
<td>

`schema_version`

</td>
<td>

Optional

</td>
<td>

There is no need to update this field. However, if incorrect the project breaks. The current version is `v2`.

</td>
</tr>
<tr>
<td>

`user_info`

</td>
<td>

Recommended

</td>
<td>

AI Workbench automatically provisions a user for you when you run the container, but this field overrides that user.

</td>
</tr>
<tr>
<td>

`package_managers`

</td>
<td>

Recommended

</td>
<td>

For each package manager in the container, specify the name of the package manager, the complete path to the manager binary, and a comma-separated list of packages installed by that manager.
If this remains unchanged, the package manager widget will likely not work, especially if you are working with a venv or conda environment.

</td>
</tr>
<tr>
<td>

`package_manager_environment`

</td>
<td>

Recommended

</td>
<td>

Specifies the package manager environment that should be activated before installing the packages and starting the applications. This setting is useful if your container uses a virtual environment or Conda when building.

</td>
</tr>
</tbody>
</table>

## Related Topics

- [Single Container Environments](/ai-workbench/reference/projects/base-environments)
- [Use a Custom Container Image](/ai-workbench/how-to/use-custom-container)
- [AI Workbench Project Containers](/ai-workbench/concepts/single-container-concept)