Bring Your Own Container (BYOC)

This is a high-level conceptual overview of how to use base images that aren’t in the set of defaults provided on NGC. For a more detailed and practical reference, see the BYOC Deep Dive.

  • NVIDIA AI Workbench offers a choice of default base images hosted on NGC to create a project. They are maintained within a Shared Responsibility Model.

  • You can then modify the environment built on top of the base image by working with environment configuration files.

  • However, you may want to start with a different base than one of those defaults, i.e. you want to “bring your own container” (BYOC).

  • The main issue for BYOC is whether or not the base image is AI Workbench compatible. These are fairly weak requirements on the Linux distro.

  • There are two ways to do this, and the most accessible one is by manually changing some fields in the Project Spec, spec.yaml.

Current Limitations

  • The UI doesn’t yet have an interface for BYOC, so the process is currently manual.

  • Bases must be an APT-based Linux distribution, e.g. Ubuntu or derived from Debian.

  • Base images that require authentication, e.g. an API key, are only supported from NGC ( and GitHub (

Basic Requirements for BYOC

  • You have a compatible base image that is in an accessible registry. This means the container is either public and not gated, or if gated it is on NGC ( or GitHub (

  • You have sufficient metadata for the base image to fill in the required fields in the Project Spec.

  • You have an existing spec.yaml file with metadata for the base image removed. This is where the above metadata for the base image of interest will be added.

  • Add project spec to .project folder.

  • Build project.

Basic Process for BYOC

  • Open the spec.yaml file in a text editor.

  • Add or update certain fields with base image data.

  • Save the changes.

  • Rebuild the project environment.

Contents, entry points, and commands

The container must

  • Be an APT-based Linux distribution, e.g. Debian based. Ubuntu is the preferred Linux distribution.

  • Not have any critical logic in the entry point or command.

  • Have CUDA installed to use GPUs.

  • Have Bash, Git and Git-lfs installed.

  • Have an appropriate version of Python and JupyterLab installed.

Requirements to Use GPUs

  • Ensure you have the updated NVIDIA Drivers installed on your host machine. On installation, AI Workbench will take care of installing the most up-to-date drivers for you if no drivers exist on the host machine.

  • Ensure NVIDIA Container Toolkit and/or NVIDIA Container Runtime is installed in the container. These are tools to build and run GPU-accelerated containers.

  • If your workflow requires CUDA, you may want to have the NVIDIA CUDA Toolkit installed in the container as well.

Access to the Base Image

To use a base image, you must be able to pull it. This requires the following information.

  • The registry URL, e.g. or

  • The image name.

  • An optional image tag.

  • Access type, gated or ungated. Currently AI Workbench only supports gated images from NGC and GitHub.

Gated Containers

These require authentication, e.g. an API key, and potentially some type of registration to pull and use. Currently, you can only use gated containers from NGC or GitHub. An example is the NVIDIA NeMo Framework Training container.

This container requires an API key as well as signing up for the GA program. You can see how to access this container in the README for the example project here

Ungated Containers

These do not require an API key or any special signup to pull and use. Any container that is AI Workbench compatible can be used. An example is the NVIDIA PyTorch container.

For BYOC you only need to update fields in the environment section of the Project Spec, .project/spec.yaml. It provides the metadata that AI Workbench interprets to combine the files in the repository with the base image to build your development environment.

For more information see

  • The BYOC deep dive here.

  • The Project Spec deep dive here.


  • All fields in the Project Spec are editable, but incorrect or partial information will typically break the project, usually the container build. Care should be taken.

  • To effect the changes made to the Project Spec, you typically have to rebuild or restart the container. You may be automatically prompted by AI Workbench to do this.

  • Changing the base image requires a moderate amount of knowledge of what is in the container and how it is configured.

The Project Spec file, .project/spec.yaml has the following sections. For more information, see the Project Spec deep dive here.


This field gives the version number of the specification used.


This section outlines the project metadata for display in AI Workbench, including creation time, project name, and project description.


This section specifies the core project directories and their storage backends, e.g. Git, Git-lfs or gitignore.


This section provides information on the project environment, including specifying the base image and the contained package managers, the CUDA version, as well as other labels and tags AI Workbench uses to create and manage your development environment.


This section provides configuration for the runtime environment, such as start and stop commands for included applications, the number of GPUs requested, as well as project secrets and/or mounts needing configuration.

For the BYOC approach, the focus is on updating fields in the environment and execution sections.


This section provides a high-level overview of the core changes needed to bring your own container to a project. For a full list of core, recommended, and optional specifications and how to approach updating them, as well as troubleshooting tips and known issues, check out the BYOC Deep Dive.

To swap any container currently in your project with a new container:

  1. Navigate to the project spec file located in the project at .project/spec.yaml using any file browser.

  2. Edit the registry and image fields of the spec file using any text editor to point to your container of interest. Save the file.


    .. code-block:: bash :linenos: registry: <your registry here, eg.,> image: <your image and tag here, eg. group/test-container:latest>

  3. (Optional) If you would like to run your container as a root user, specify the following as well. Otherwise, a non-root user will automatically be provisioned by AI Workbench to run the container environment.


    .. code-block:: bash :linenos: user_info: uid: "0" gid: "0" username: "root"

  4. Edit other fields of the project spec to provide AI Workbench with proper metadata to work with the new container. For a full list of core, recommended, and optional specifications and how to approach updating them, check out the BYOC Deep Dive.

  5. Rebuild your project environment. On the Desktop, select the Build button for your project. On Command Line, run nvwb build inside the project.

  6. When the build completes, start and/or restart any applications in the project to utilize the new container in the project environment.

Previous User Interface
Next Windows Installation
© Copyright 2023-2024, NVIDIA. Last updated on Jan 21, 2024.