> 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.

# Single Container Environments

**This page documents the base image options and custom container label specification for AI Workbench project containers.**

For conceptual background, see [AI Workbench Project Containers](/ai-workbench/concepts/single-container-concept).
For step-by-step procedures to customize environments, see [Walkthrough: Customize Your Environment](/ai-workbench/quickstart/quickstart-environment).
For instructions on creating a custom base image, see [Use a Custom Container Image](/ai-workbench/how-to/use-custom-container).

## NVIDIA Default Base Images

**NVIDIA provides pre-configured base images on NGC.**

Each default image has Python and JupyterLab pre-installed.
The PyTorch image also includes TensorBoard.

| **Image** | **Description** |
|---|---|
| [PyTorch](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/ai-workbench/containers/pytorch) | Python, JupyterLab, PyTorch, and TensorBoard. |
| [Python Basic](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/ai-workbench/containers/python-basic) | Python and JupyterLab. |
| Python with CUDA | Python, JupyterLab, and CUDA toolkit. Available versions: [11.7](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/ai-workbench/containers/python-cuda117), [12.0](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/ai-workbench/containers/python-cuda120), [12.2](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/ai-workbench/containers/python-cuda122). |
| [RAPIDS with CUDA 12.0](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/rapidsai/containers/notebooks) | RAPIDS libraries with CUDA 12.0. |

<Note title="Additional images may be available.">

For the full list of available containers, see [NVIDIA NGC Containers](https://catalog.ngc.nvidia.com/containers?query=workbench).

</Note>

## Custom Base Images (BYOC)

**You can use your own container image as the base for a project.**

| **Requirement** | **Description** |
|---|---|
| **Operating System** | The base image should be Debian-based. |
| **Image Labels** | The base image must include [Docker image labels](https://docs.docker.com/reference/dockerfile/#label) according to the label specification below. |
| **Registry Access** | The base image must be published to a container registry accessible from the host. |

### Supported Registries

| **Registry** | **Description** |
|---|---|
| **NVIDIA GPU Cloud (NGC)** | `nvcr.io`. Supports private images with NVIDIA account authentication. |
| **Docker Hub** | `docker.io`. Default registry. Public images only. |
| **GitHub Container Registry** | `ghcr.io`. Supports private images with GitHub OAuth. |
| **GitLab Container Registry** | `registry.gitlab.com`. Supports private images with GitLab OAuth. |
| **Self-hosted GitLab** | Custom GitLab registry URLs. Supports private images with GitLab OAuth. |

<Note title="Private registries on other platforms are not supported.">

AI Workbench does not support pulling from private registries on platforms other than those listed above (e.g., DockerHub private repos).

</Note>

## Custom Container Label Specification

**AI Workbench uses Docker labels to read metadata from custom base images.**

Labels tell AI Workbench about the operating system, installed software, package managers, and available applications in your base image.
All labels follow the convention `com.nvidia.workbench.<field-name>`.
Labels in parent images are inherited and can be overridden in child images.

### Required Labels

**These five labels are required for AI Workbench to recognize a custom base image.**

| **Label** | **Description** |
|---|---|
| `com.nvidia.workbench.name` | Display name shown in the AI Workbench UI. |
| `com.nvidia.workbench.description` | Brief description shown in the AI Workbench UI. |
| `com.nvidia.workbench.schema-version` | Must be `v2`. Indicates the label schema version. |
| `com.nvidia.workbench.image-version` | Semantic version for sorting multiple image versions in the UI and CLI. |
| `com.nvidia.workbench.cuda-version` | CUDA version for driver compatibility checks. Set to an empty string if CUDA is not installed. |

```dockerfile
LABEL com.nvidia.workbench.name="PyTorch with CUDA 12.2"
LABEL com.nvidia.workbench.description="PyTorch 2.1 environment with CUDA 12.2 and JupyterLab"
LABEL com.nvidia.workbench.schema-version="v2"
LABEL com.nvidia.workbench.image-version="1.0.5"
LABEL com.nvidia.workbench.cuda-version="12.2"
```

### Recommended Labels

**These labels enable important AI Workbench features and should be included.**

#### Operating System Labels

| **Label** | **Description** |
|---|---|
| `com.nvidia.workbench.os` | Operating system name. Typically `linux`. |
| `com.nvidia.workbench.os-distro` | OS distribution name (e.g., `ubuntu`, `debian`). |
| `com.nvidia.workbench.os-distro-release` | OS distribution version (e.g., `22.04`). |
| `com.nvidia.workbench.programming-languages` | Space-separated list of installed programming languages (e.g., `python3`). |

```dockerfile
LABEL com.nvidia.workbench.os="linux"
LABEL com.nvidia.workbench.os-distro="ubuntu"
LABEL com.nvidia.workbench.os-distro-release="22.04"
LABEL com.nvidia.workbench.programming-languages="python3"
```

#### Package Manager Labels

**Package manager labels are required for the package manager widget in the Desktop App to function.**

| **Label** | **Description** |
|---|---|
| `com.nvidia.workbench.package-manager.<name>.binary` | Absolute path to the package manager binary. Replace `<name>` with the manager name (`apt`, `pip`, `conda`, etc.). |
| `com.nvidia.workbench.package-manager.<name>.installed-packages` | Space-separated list of packages installed by this manager. Can list key packages rather than all. |
| `com.nvidia.workbench.package-manager-environment.type` | Virtual environment type. Valid values: `conda` or `venv`. |
| `com.nvidia.workbench.package-manager-environment.target` | Absolute path to the virtual environment or Conda installation directory. |

```dockerfile
# Package managers
LABEL com.nvidia.workbench.package-manager.apt.binary="/usr/bin/apt"
LABEL com.nvidia.workbench.package-manager.apt.installed-packages="curl git vim"
LABEL com.nvidia.workbench.package-manager.conda.binary="/opt/conda/bin/conda"
LABEL com.nvidia.workbench.package-manager.conda.installed-packages="python=3.11 pytorch cudatoolkit"
LABEL com.nvidia.workbench.package-manager.pip.binary="/opt/conda/bin/pip"
LABEL com.nvidia.workbench.package-manager.pip.installed-packages="jupyterlab"

# Conda environment
LABEL com.nvidia.workbench.package-manager-environment.type="conda"
LABEL com.nvidia.workbench.package-manager-environment.target="/opt/conda"
```

### Optional Labels

#### User Management Labels

**AI Workbench automatically creates a default workbench user with UID/GID 1000 and sudo access.**

If your base image has an existing user with files and permissions already configured, use these labels to preserve that user.
AI Workbench adjusts the specified user to UID 1000 while preserving the username.

| **Label** | **Description** |
|---|---|
| `com.nvidia.workbench.user.uid` | UID of an existing user in the base image. AI Workbench adjusts this user to UID 1000 during build. |
| `com.nvidia.workbench.user.gid` | GID of an existing user in the base image. |
| `com.nvidia.workbench.user.username` | Username of an existing user. Preserved when AI Workbench adjusts the UID. |

```dockerfile
LABEL com.nvidia.workbench.user.uid="1001"
LABEL com.nvidia.workbench.user.gid="1000"
LABEL com.nvidia.workbench.user.username="rapids"
```

#### Display and Search Labels

| **Label** | **Description** |
|---|---|
| `com.nvidia.workbench.labels` | Comma-separated search keywords or tags for filtering in the Desktop App. |
| `com.nvidia.workbench.icon` | URL to an icon image displayed when selecting base images. |
| `com.nvidia.workbench.build-timestamp` | Build timestamp in `YYYYMMDDHHMMSS` format. AI Workbench auto-updates this during project container builds. |

#### Container Behavior Labels

| **Label** | **Description** |
|---|---|
| `com.nvidia.workbench.entrypoint-script` | Path to a base image entrypoint script to preserve. AI Workbench sets `NVWB_BASE_ENV_ENTRYPOINT` to this path and calls it from its own entrypoint wrapper. |

```dockerfile
LABEL com.nvidia.workbench.entrypoint-script="/home/rapids/entrypoint.sh"
```

**The preserved base-image entrypoint is different from a project's onStart.bash script.**

AI Workbench runs the entrypoint identified by this label first and then runs the project-root `onStart.bash` script.
For project-specific startup actions, see [Use the onStart.bash Script](/ai-workbench/how-to/environments/onstart-script).

## Application Labels

**Application labels integrate applications with the AI Workbench Application Launcher.**

All application labels follow the pattern `com.nvidia.workbench.application.<name>.<property>`.
These labels are optional but enable automatic application startup, health monitoring, and URL discovery.

### Application Classes

| **Class** | **Description** |
|---|---|
| `webapp` | Web applications accessed through a browser (e.g., JupyterLab, TensorBoard). |
| `process` | Background processes without a UI (e.g., training scripts, data processing). |
| `native` | Applications that launch natively on the host (e.g., VS Code). |

### Common Application Labels

**These labels apply to all application classes.**

| **Label** | **Description** |
|---|---|
| `application.<name>.type` | Type identifier. Can be a standard type (`jupyterlab`, `tensorboard`) or a custom name. |
| `application.<name>.class` | Application class. Valid values: `webapp`, `process`, `native`. |
| `application.<name>.start-cmd` | Shell command to start the application. Must not be a blocking command. |
| `application.<name>.stop-cmd` | Shell command to stop the application gracefully. |
| `application.<name>.health-check-cmd` | Shell command to check if the application is healthy. Returns 0 if healthy, non-zero otherwise. |
| `application.<name>.timeout-seconds` | Seconds to wait for health check to pass. Valid range: 1–3600. Default: 60. |
| `application.<name>.user-msg` | Message displayed when the application starts. Use `{{.URL}}` as a placeholder for the webapp URL. |
| `application.<name>.icon-url` | URL to an icon image for the application. |

### Webapp-Specific Labels

**These labels are required for applications with** `class="webapp"`.

| **Label** | **Description** |
|---|---|
| `application.<name>.webapp.port` | Port number the web application listens on. |
| `application.<name>.webapp.autolaunch` | Whether to automatically open the URL in a browser. Valid values: `true`, `false`. |
| `application.<name>.webapp.url` | Static URL for the application. Use when the URL is predictable. |
| `application.<name>.webapp.url-cmd` | Shell command to discover the URL dynamically. Use when the URL changes (e.g., includes a token). |
| `application.<name>.webapp.proxy.trim-prefix` | Whether the AI Workbench reverse proxy removes the application-specific URL prefix before forwarding. Valid values: `true`, `false`. |

### Process-Specific Labels

| **Label** | **Description** |
|---|---|
| `application.<name>.process.wait-until-finished` | Whether the Desktop App waits for the process to complete and notifies you when it finishes. The CLI always waits. Valid values: `true`, `false`. |

### Application Label Examples

**JupyterLab webapp:**

```dockerfile
LABEL com.nvidia.workbench.application.jupyterlab.type="jupyterlab"
LABEL com.nvidia.workbench.application.jupyterlab.class="webapp"
LABEL com.nvidia.workbench.application.jupyterlab.start-cmd="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='*'"
LABEL com.nvidia.workbench.application.jupyterlab.stop-cmd="jupyter lab stop 8888"
LABEL com.nvidia.workbench.application.jupyterlab.health-check-cmd="[ \\$(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' ]"
LABEL com.nvidia.workbench.application.jupyterlab.timeout-seconds="90"
LABEL com.nvidia.workbench.application.jupyterlab.webapp.port="8888"
LABEL com.nvidia.workbench.application.jupyterlab.webapp.autolaunch="true"
LABEL com.nvidia.workbench.application.jupyterlab.webapp.url-cmd="jupyter lab list | head -n 2 | tail -n 1 | cut -f1 -d' ' | grep -v 'Currently'"
```

**TensorBoard webapp:**

```dockerfile
LABEL com.nvidia.workbench.application.tensorboard.type="tensorboard"
LABEL com.nvidia.workbench.application.tensorboard.class="webapp"
LABEL com.nvidia.workbench.application.tensorboard.start-cmd="tensorboard --logdir \\$TENSORBOARD_LOGS_DIRECTORY --path_prefix=\\$PROXY_PREFIX --bind_all"
LABEL com.nvidia.workbench.application.tensorboard.health-check-cmd="[ \\$(curl -o /dev/null -s -w '%{http_code}' http://localhost:\\$TENSORBOARD_PORT\\$PROXY_PREFIX/) == '200' ]"
LABEL com.nvidia.workbench.application.tensorboard.timeout-seconds="90"
LABEL com.nvidia.workbench.application.tensorboard.webapp.port="6006"
LABEL com.nvidia.workbench.application.tensorboard.webapp.autolaunch="true"
LABEL com.nvidia.workbench.application.tensorboard.webapp.url="http://localhost:6006"
```

## Related Topics

- [AI Workbench Project Containers](/ai-workbench/concepts/single-container-concept) - Conceptual overview of containers and environments
- [Walkthrough: Customize Your Environment](/ai-workbench/quickstart/quickstart-environment) - How to customize a project environment with packages and scripts
- [Use a Custom Container Image](/ai-workbench/how-to/use-custom-container) - How to create a fully custom base image
- [Container Specification](/ai-workbench/reference/projects/spec#container-specification) - How to change container behavior for a single project
- [Use Multi-Container Environments](/ai-workbench/how-to/environments/multi-container) - How to run additional containers alongside the project container
- [AI Workbench Project Specification](/ai-workbench/reference/projects/spec) - Full specification file reference
- [Manage Packages](/ai-workbench/how-to/environments/package-management) - Managing packages in containers