Is this page helpful?

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.