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

## Overview

**AI Workbench builds a container image for your development environment.**

The image is defined from the project spec file and the (optional) configuration files.
[See here.](/ai-workbench/reference/projects/project-reference-overview#project-structure)

The [spec file](/ai-workbench/reference/projects/spec) defines the base image and other build information, while
the configuration files provide package lists and scripts to be run during the build.

AI Workbench renders the information in a containerfile that it runs to build the container image.

**AI Workbench creates and runs a project container using the configuration stored in the repository.**

When you start a project, AI Workbench creates a container from the image and configures it with the runtime
configuration from the project spec and other files in the repository.

This includes settings such as environment variables, mounts, networking, and GPU access. The runtime configuration (except for secret values) is versioned with the repository.
[See here.](/ai-workbench/reference/projects/runtime-configuration-reference)

**Your code, data and configuration are stored in the repository outside of the container.**

The repository is stored on disk and mounted into the container at runtime.
This allows your files to persist and be portable independently of the container's ephemeral file system.

**The project container is removed each time you stop the project.**

The container is a temporary runtime environment. Removing it ensures that the latest runtime configuration is applied the next time you start the project container.
This lets you update the environment and prevents stale runtime state.

## Key Concepts

**Base Image**

The starting image used as a foundation for the project container.
It is pulled from a container repository specified by a URL in the project spec file, `.project/spec.yaml`.

**Container Build Scripts**

Optional user-edited scripts in the repository (`preBuild.bash`, `postBuild.bash`) that AI Workbench includes during the container build.
Use them to script modifications that become part of the container image.

**Environment Configuration Files**

Optional package files (`apt.txt`, `requirements.txt`) in the repository that AI Workbench includes during the container build to let you add packages.

**Build Context**

An isolated folder with AI Workbench-generated files (entrypoint, containerfile) and selected files copied from the project repository.

**Generated Entrypoint**

An `entrypoint.sh` file that AI Workbench dynamically renders into the build context.
The generated entrypoint coordinates the preserved base-image entrypoint, the project startup script, and removal of passwordless `sudo` before the normal project container process begins.
AI Workbench does not store this generated file in the project repository.

**Project Container**

The container that AI Workbench runs for your development environment.
It uses the base image as a starting point and includes additional runtime configurations.

**Runtime Configuration**

User-entered settings applied when starting the container.

Includes the key-value pairs stored in the `variables.env`, the GPU configuration
in the `spec.yaml` file, and the secrets keys from the project runtime folder.
Also includes the startup script (`onStart.bash`).

**Startup Script**

Optional script (`onStart.bash`) that AI Workbench runs every time it creates and starts the project container.
The script can access the mounted project and running container environment without the limitations of the build context.
It runs with temporary passwordless `sudo` access during container startup.

**Project Runtime Folder**

A sub folder of `~/.nvwb/project-runtime-info` that AI Workbench creates on the host to cache environment information that lives outside of
the project repository.

Contains copies of the environment configuration files, the formatted entrypoint and containerfile, as well as the user-specific secrets that
shouldn't be kept in the repository.

## Build Context Limitations

**The build context can't access the entire project repository or the environment variables.**

The build context is prescriptively limited to the following files:

- The formatted entrypoint and containerfile
- The optional configuration files from the repository (if present)
- The spec file

Furthermore, you can't manually add things to the build context because it is dynamically generated.

**You must account for the fixed build context when writing the** `preBuild.bash` **or** `postBuild.bash` **scripts.**

For example, the following will fail in the build scripts:

- Invoking environment variables defined in *variables.env*
- Direct *pip* or *apt* installs from source files in the project
- Copying files from the project
- Changing directory into */project/*

However, you can add dependencies from external sources.
PyPi installs should be done using the package files.
*pip* installs from GitHub should be done in one of the build scripts.

Furthermore, there are workarounds to include custom, locally defined packages during the build or at runtime.
You can find them in the How To sections.

## Container Management and Use

**Configuration file edits are tracked, and diffs queue up a container rebuild or restart to implement changes.**

For example, editing the environment configuration triggers Desktop App notifications but
the actual changes aren't implemented until you restart or rebuild the project container.

**AI Workbench has a three-step managed process to build the container image.**

1. Copy the project spec and build-related files, including container build scripts and environment configuration files, into the project runtime folder on the host.
2. Render an entrypoint script and containerfile in the project runtime folder.
3. Build the container image from the containerfile.

AI Workbench does not put the generated entrypoint or containerfile in the repository.

**AI Workbench can run commands in the container to manage applications, packages and files.**

You can start and stop applications and manage packages using features in the Desktop App and CLI.
AI Workbench has the commands configured and runs them in the container.

For web applications, [the proxy service](/ai-workbench/reference/workbench-application/proxy) provides a single configuration for ports, so you
don't need to stop/start the container to add ports.

## Project Container Startup

**AI Workbench runs project startup customization after it mounts the project.**

The generated entrypoint runs the preserved base-image entrypoint first and then runs the project-root `onStart.bash` script.
Unlike build scripts, `onStart.bash` can access files in the project mount.

**The startup script initializes each newly created project container.**

It runs as the project user with passwordless `sudo` available until the script finishes.
Passwordless `sudo` is not available in the normally running project container after startup.
For startup behavior and editing procedures, see [Use the onStart.bash Script](/ai-workbench/how-to/environments/onstart-script).