Skip to navigation
ReferenceProjects and Environments

Single Container Environments

View as Markdown

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.

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

RequirementDescription
Operating SystemThe base image should be Debian-based.
Image LabelsThe base image must include Docker image labels according to the label specification below.
Registry AccessThe base image must be published to a container registry accessible from the host.

Supported Registries

RegistryDescription
NVIDIA GPU Cloud (NGC)nvcr.io. Supports private images with NVIDIA account authentication.
Docker Hubdocker.io. Default registry. Public images only.
GitHub Container Registryghcr.io. Supports private images with GitHub OAuth.
GitLab Container Registryregistry.gitlab.com. Supports private images with GitLab OAuth.
Self-hosted GitLabCustom 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.

LabelDescription
com.nvidia.workbench.nameDisplay name shown in the AI Workbench UI.
com.nvidia.workbench.descriptionBrief description shown in the AI Workbench UI.
com.nvidia.workbench.schema-versionMust be v2. Indicates the label schema version.
com.nvidia.workbench.image-versionSemantic version for sorting multiple image versions in the UI and CLI.
com.nvidia.workbench.cuda-versionCUDA 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"

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

Operating System Labels

LabelDescription
com.nvidia.workbench.osOperating system name. Typically linux.
com.nvidia.workbench.os-distroOS distribution name (e.g., ubuntu, debian).
com.nvidia.workbench.os-distro-releaseOS distribution version (e.g., 22.04).
com.nvidia.workbench.programming-languagesSpace-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.

LabelDescription
com.nvidia.workbench.package-manager.<name>.binaryAbsolute path to the package manager binary. Replace <name> with the manager name (apt, pip, conda, etc.).
com.nvidia.workbench.package-manager.<name>.installed-packagesSpace-separated list of packages installed by this manager. Can list key packages rather than all.
com.nvidia.workbench.package-manager-environment.typeVirtual environment type. Valid values: conda or venv.
com.nvidia.workbench.package-manager-environment.targetAbsolute 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.

LabelDescription
com.nvidia.workbench.user.uidUID of an existing user in the base image. AI Workbench adjusts this user to UID 1000 during build.
com.nvidia.workbench.user.gidGID of an existing user in the base image.
com.nvidia.workbench.user.usernameUsername 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

LabelDescription
com.nvidia.workbench.labelsComma-separated search keywords or tags for filtering in the Desktop App.
com.nvidia.workbench.iconURL to an icon image displayed when selecting base images.
com.nvidia.workbench.build-timestampBuild timestamp in YYYYMMDDHHMMSS format. AI Workbench auto-updates this during project container builds.

Container Behavior Labels

LabelDescription
com.nvidia.workbench.entrypoint-scriptPath 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"

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.

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

ClassDescription
webappWeb applications accessed through a browser (e.g., JupyterLab, TensorBoard).
processBackground processes without a UI (e.g., training scripts, data processing).
nativeApplications that launch natively on the host (e.g., VS Code).

Common Application Labels

These labels apply to all application classes.

LabelDescription
application.<name>.typeType identifier. Can be a standard type (jupyterlab, tensorboard) or a custom name.
application.<name>.classApplication class. Valid values: webapp, process, native.
application.<name>.start-cmdShell command to start the application. Must not be a blocking command.
application.<name>.stop-cmdShell command to stop the application gracefully.
application.<name>.health-check-cmdShell command to check if the application is healthy. Returns 0 if healthy, non-zero otherwise.
application.<name>.timeout-secondsSeconds to wait for health check to pass. Valid range: 1–3600. Default: 60.
application.<name>.user-msgMessage displayed when the application starts. Use {{.URL}} as a placeholder for the webapp URL.
application.<name>.icon-urlURL to an icon image for the application.

Webapp-Specific Labels

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

LabelDescription
application.<name>.webapp.portPort number the web application listens on.
application.<name>.webapp.autolaunchWhether to automatically open the URL in a browser. Valid values: true, false.
application.<name>.webapp.urlStatic URL for the application. Use when the URL is predictable.
application.<name>.webapp.url-cmdShell command to discover the URL dynamically. Use when the URL changes (e.g., includes a token).
application.<name>.webapp.proxy.trim-prefixWhether the AI Workbench reverse proxy removes the application-specific URL prefix before forwarding. Valid values: true, false.

Process-Specific Labels

LabelDescription
application.<name>.process.wait-until-finishedWhether 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"