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. For step-by-step procedures to customize environments, see Walkthrough: Customize Your Environment. For instructions on creating a custom base image, see Use a Custom Container Image.

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	Python, JupyterLab, PyTorch, and TensorBoard.
Python Basic	Python and JupyterLab.
Python with CUDA	Python, JupyterLab, and CUDA toolkit. Available versions: 11.7, 12.0, 12.2.
RAPIDS with CUDA 12.0	RAPIDS libraries with CUDA 12.0.

Additional images may be available.

For the full list of available containers, see NVIDIA NGC Containers.

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

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

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.

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

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.

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

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.

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

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:

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:

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"