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

# The Project Specification

## Overview

**AI Workbench reads and writes to the project specification file to manage a Git repository.**

The "spec file" is written to `.project/spec.yaml` at the top of the repository, and
its main job is to defines what goes into the container build and what happens at runtime.

AI Workbench can't manage a repository without a valid spec file.

**The spec file has four sections: meta, layout, environment, and execution.**

- Meta identifies the project.
- Layout maps directory structure to storage backends.
- Environment defines the container build (base image, installed apps, packages).
- Execution defines runtime behavior (GPU requests, mounts, secrets, custom apps).

**The Desktop App and CLI provide features for editing most spec fields, but you can also edit the file directly.**

Manual editing requires following the YAML schema.

If you break the file while editing it, you will need to fix it but the damage isn't permanent because you can
use the Git versioning to throw away your changes and start again..

**If you clone a repository without a spec file, AI Workbench detects this and scaffolds a default one.**

You select a base image and AI Workbench generates a minimal working specification.
You can customize it afterward.

## Key Concepts

**Meta**

Project identity fields: name, image, description, labels, default branch, and creation date.
The name drives container naming, runtime folder paths, and display in the UI.

**Layout**

Maps directories to storage backends: `git`, `gitlfs`, or `gitignore`.
AI Workbench reconciles layout entries with `.gitattributes` and `.gitignore`.

**Environment Section**

Container build configuration.
Contains the base image reference, installed applications, package managers, and OS metadata.
Manual edits to `environment.base` are overridden when the environment version is updated.

**Execution Section**

Runtime configuration.
Contains custom applications, GPU requests, shared memory, secrets (keys only), and mounts.

**Environment Apps vs Execution Apps**

`environment.base.apps` are applications installed in the base image, such as JupyterLab.
`execution.apps` are custom applications you add to the project that are not part of the base image.

**Spec Version**

The schema version (currently `v2`) that AI Workbench uses to validate and interpret the file.

## Build vs Runtime

**The environment section and layout feed the container build.**

The base image, package managers, build scripts, and layout backends all shape what goes into the containerfile that AI Workbench generates.
Editing these requires a rebuild.

**The execution section feeds the container run.**

GPU requests, mounts, secrets, and custom apps are applied when the container starts.
Editing these requires a restart, not a rebuild.

**Some information spans both.**

Apps defined in `environment.base.apps` are built into the image but also have runtime behavior (start/stop commands, health checks, ports).
Secret keys are versioned in the spec but values are stored in the project runtime folder on each host.

## What the Spec File Does Not Manage

**The spec file does not manage Git history, remotes, or individual project files.**

It defines the container, not the repository content.
The one exception is the `compose_file_path` field, which points to a compose file in the repository.

**The spec file does not contain the generated containerfile or entrypoint.**

AI Workbench generates these into the project runtime folder (`~/.nvwb/runtime/<PROJECT-NAME>/`) during the build.
They are not versioned.

**Secret values are not in the spec file.**

Only the secret key and description are versioned.
The actual values live in `secrets.env` in the project runtime folder on each host and must be re-entered when cloning to a new machine.

## Related Topics

- [AI Workbench Project Specification](/ai-workbench/reference/projects/spec) - Full specification field reference
- [AI Workbench Projects](/ai-workbench/concepts/project-concept) - How projects work in AI Workbench
- [AI Workbench Project Containers](/ai-workbench/concepts/single-container-concept) - Containers, images, and the build process
- [Work with Any Git Repository](/ai-workbench/how-to/convert-repo) - How to bring any Git repository into AI Workbench
- [Runtime Configuration (Environment Variables and Mounts)](/ai-workbench/reference/projects/runtime-configuration-reference) - Mounts and environment variable specifications