Is this page helpful?

AI Workbench Projects Reference#

Overview#

This reference provides technical specifications for AI Workbench projects.

Use this reference to understand:

Project structure requirements and file specifications.
How AI Workbench registers and tracks projects.
Project metadata and inventory management.
Required and optional configuration files.
Project lifecycle operations (creation, cloning, migration).
Platform-specific behaviors and constraints.

For conceptual understanding of projects, see AI Workbench Projects.

For step-by-step procedures, see How to Work with AI Workbench Projects.

Key Concepts#

The key concepts for AI Workbench projects are:

Project Registration: The process by which AI Workbench adds project metadata to $HOME/.nvwb/inventory.json and creates runtime folders
Project Runtime Metadata: Files AI Workbench creates outside the repository to track project state, container IDs, and local configurations.
Project Specification: The .project/spec.yaml file containing project configuration (see AI Workbench Project Specification for complete field reference).
Project Structure: The standardized directory layout and file organization AI Workbench expects.

Requirements#

System Requirements#

The system requirements for AI Workbench projects are:

Git: Must be installed and configured with user.name and user email.
Container Runtime: Docker Desktop (Windows/macOS) or Docker Engine (Linux).
AI Workbench: Desktop App or CLI installed.
Disk Space: Minimum 5 GB free space for base environments.

Platform-Specific Requirements#

The platform-specific requirements for AI Workbench projects are different for different platforms.

Windows#

The Windows requirements for AI Workbench projects are:

WSL2 with Ubuntu distribution
AI Workbench creates projects in WSL2 filesystem
Windows paths must use WSL2/UNIX paths (e.g., “/home/user/” not “C:Users").

macOS#

The macOS requirements for AI Workbench projects are:

macOS with Apple Silicon or Intel architecture.
Docker Desktop installed.

Project Structure#

The project structure for AI Workbench projects is:

Note

To make a Git repository into an AI Workbench project, create the .project/spec.yaml file. For the full specification file reference, see AI Workbench Project Specification for complete field reference.

File or Folder	Description	Required?	Tracked by Git?
.project/configpacks	Tracks when configpacks are run to avoid duplication.	Yes.	Yes.
.project/spec.yaml	Metadata defining the project. For the full reference, see here.	Yes.	Yes.
code/	Suggested location for your code files.	No.	Yes.
data/	Suggested location for your data files.	No.	Yes. Tracked by Git LFS.
data/scratch	Suggested location for intermediate data products.	No	No. Ignored by Git.
models/	Suggested location for your models.	No.	Yes. Tracked by Git LFS.
.gitattributes	Defines Git attributes for relevant folders. For more information, see here.	Yes.	Yes.
.gitignore	Lists files and folders that you don’t want tracked by Git. The default targets typical python development. For more information, see here.	Yes.	Yes.
apt.txt	Adds apt packages to your project. Specify 1 package per line. For more information, see here.	No.	Yes.
postBuild.bash	Runs after installing packages. Runs as the container user with passwordless sudo access. For more information, see here.	No.	Yes.
preBuild.bash	Runs before installing packages. Runs as the container user with passwordless sudo access. For more information, see here.	No.	Yes.
README.md	The README file for your project, written in markdown.	No.	Yes.
requirements.txt	Adds pip packages to your project. Specify 1 package per line. For more information, see here.	No.	Yes.
variables.env	Non-sensitive environment variables set in the container at runtime. Variables are not built into the container image.	No.	Yes.

Required Files#

AI Workbench requires a .project/ hidden directory at the repository root. The following required files are required:

.project/spec.yaml
.project/configpack

These files properties are described in the following sections.

.project/spec.yaml#

Purpose: Core configuration file defining project metadata, environment, and applications.
Format: YAML.
Required: Yes - project will not open without valid spec.yaml.
Managed By: AI Workbench (automatically edited during UI operations).
Manual Editing: Possible but risky - validation using nvwb validate is recommended.
Reference: See AI Workbench Project Specification for complete field specification.

.project/configpack#

The .project/configpack file is required for the following reasons:

Purpose: Stores project-specific default configurations
Format: Plain text key-value pairs
Required: Yes (created automatically)
Managed By: AI Workbench
Manual Editing: Not recommended

Example minimal project structure:

my-project/

.project/
spec.yaml # Required: configpack # Required

.git/ # Required (Git repository)

.gitignore # Recommended: README.md # Recommended

Optional Configuration Files#

The following are optional configuration files for AI Workbench projects:

Build Configuration Files#

The build configuration files are located at the repository root and are used during container build.

apt.txt
- Lists Debian packages to install using apt-get.
- One package per line
- Installed before requirements.txt
Example:
```
vim
curl``
build-essential
```
requirements.txt
- Lists Python packages to install using pip.
- Standard pip requirements format
- Installed after apt.txt
Example:
```
numpy>=1.24.0
pandas==2.0.1
scikit-learn
```
preBuild.bash
- Bash script executed before package installation
- Runs during container build
- Use for: downloading files, setting up directories, environment prep
- Runs with sudo privileges
postBuild.bash
- Bash script executed after package installation
- Runs during container build
- Use for: configuration, additional setup, verification
- Runs with sudo privileges

Version Control Configuration#

gitattributes
- Created automatically for new projects
- Configures Git LFS for data/ and models/ directories
- Can be customized for additional LFS patterns
.gitignore
- Not created automatically
- Recommended for excluding build artifacts, cache files, etc.

Project Metadata and Registration#

Inventory Management#

AI Workbench maintains a JSON inventory of all registered projects. The inventory file is located at $HOME/.nvwb/inventory.json.

The inventory file contains the following information:

name: Project name
path: Project path
location: Project location
last_opened: Last opened timestamp

Example:

{
  "projects": [
    {
      "name": "my-project",
      "path": "/home/user/projects/my-project",
      "location": "local",
      "last_opened": "2024-01-15T10:30:00Z"
    }
  ]
}

Consequence: Projects created with git clone or git init outside AI Workbench will NOT be registered and cannot be opened.

Solution: Always use AI Workbench to clone or create projects.

Runtime Metadata Folder#

The runtime metadata folder is located at $HOME/.nvwb/runtime/<PROJECT-NAME>/.

AI Workbench creates a runtime folder for each project containing:

Container state information
Local configuration overrides
Application runtime data
Build cache metadata

This folder is NOT part of the Git repository and does NOT sync across locations.

Project Lifecycle#

The project lifecycle is the process of creating, cloning, and migrating projects.

Project Creation#

To create a new project, you can use the Desktop App or the CLI.

Using the Desktop App#

To create a project using the Desktop App, follow these steps:

Go to the Create New Project button.
Choose the method type you want your project to be created as:
- Blank project
- Example project
- Custom container

Using the CLI#

To create a project using the CLI, follow these steps:

Run the following code to create a project:
```
nvwb create project <PROJECT-NAME>
```

Project Cloning#

To clone a project, you can use the Desktop App or the CLI.

Using the Desktop App#

To clone a project using the Desktop App, follow these steps:

Go to the Clone Project button.
Enter the Git URL of the repository you want to clone.

Using the CLI#

To clone a project using the CLI, follow these steps:

Run the following code to clone a project:

nvwb clone project <GIT-URL>

The following happens when you clone a project:

It clones the Git repository
Validates .project/spec.yaml exists
It adds an entry to the inventory
It creates a runtime metadata folder
It does NOT build the container automatically

Project Migration#

Moving projects between locations requires re-registration. The following happens when you move a project repository manually:

Old inventory entry remains (will show “path not found”).
Must clone again using the AI Workbench CLI to re-register.
Runtime metadata does NOT transfer.

Note

Best Practice: Always use the nvwb clone command to clone the project on the new location rather than copying files.

Configuration Details#

Project Naming#

The project name has the following requirements:

It is defined in .project/spec.yaml under meta.name.
It must be unique within a location.
It is used for container naming and runtime folder paths.
It can contain letters, numbers, hyphens, underscores.
It cannot contain spaces or special characters.

Note

Renaming requires editing spec.yaml and may require rebuilding containers.

Project Locations#

Local Projects:

Stored on local machine filesystem
Container runs on local Docker
Full feature support

Remote Projects:

Stored on remote machine filesystem
Container runs on remote Docker
Accessed via SSH tunnel
Some UI operations may have higher latency

Build Behavior#

The build behavior for AI Workbench projects is different for different build types.

Quick Builds:

Automatic rebuild triggered by changes to requirements.txt, apt.txt, or preBuild.bash or postBuild.bash scripts.
Container will continue running during the process.

Full Build:

Manual rebuild triggered by clicking the Build button in the Desktop App or running the nvwb build command in the CLI.
Container will stop during the process.

Automatic Rebuild Triggers:

AI Workbench detects changes to these files and prompts for rebuild:

.project/spec.yaml (environment section)
apt.txt
requirements.txt
preBuild.bash
postBuild.bash

Manual Rebuild:

Desktop App#

Go to the Project Tab.
Click the Rebuild Environment button.

CLI#

To rebuild the container using the CLI, follow these steps:

Run the following code to rebuild the container:

nvwb build project <PROJECT-NAME>

Examples#

Example 1: Minimal Python Project#

Minimal project for Python data science:

my-analysis/

.project/
spec.yaml # PyTorch base environment: configpack

.git/

requirements.txt # pandas, matplotlib, seaborn

notebooks/: analysis.ipynb
data/ # Git LFS tracked: README.md

Example 2: Multi-Container Application#

Project with web app + database:

web-app/
------.project/
 spec.yaml          # References compose.yaml
 configpack
 .git/
 compose.yaml           # Defines web + db services
 app/
server.py
 requirements.txt
README.md

See Multi-Container Environments (Docker Compose) for Docker Compose configuration.

Example 3: Custom Container Project#

Project using fully custom container:

custom-env/
.project/
 spec.yaml          # Points to custom registry image
 configpack
 .git/
 Dockerfile             # NOT used by AI Workbench
 README.md

Note

AI Workbench uses pre-built images specified in .project/spec.yaml, not Dockerfiles in the repository.

Advanced Topics#

Spec.yaml Validation#

To validate spec.yaml without opening the project, run the following code:

nvwb validate <PATH-TO-PROJECT>

The command will return validation errors and warnings.

Project Portability#

AI Workbench projects are portable across different machines, users, and platforms as long as the base environment is accessible from the new location and a few other requirements are met.

Projects are portable across:#

Projects are portable across:

Different machines (local - remote)
Different users
Different platforms (Windows - macOS - Linux)

Requirements for portability:#

The requirements for portability are:

Base environment must be accessible from new location.
Required files (apt.txt, requirements.txt) are versioned.
Paths in spec.yaml use container paths, not host paths.
Git remote must be accessible.

Constraints and Limitations#

AI Workbench projects have the following constraints and limitations:

Project Name Constraints:#

The project name constraints are:

Must be unique within a location.
Cannot be changed easily (requires spec.yaml edit + rebuild).

Container Constraints:#

The container constraints are:

One container per project (or Docker Compose multi-container).
Container must be based on Linux.
Windows containers not supported.

What Else is Covered?#

Project Reference Topics#
Runtime Configuration	Runtime Configuration
GPU Configuration	GPU Configuration
Containers	Containers Reference
Multi-Container Environments	Multi-Container Environments Reference
Spec	Spec Reference
VS Code	VS Code Reference
Base Environments	Base Environments Reference

AI Workbench Projects Reference#

Overview#

Key Concepts#

Requirements#

System Requirements#

Platform-Specific Requirements#

Windows#

macOS#

Project Structure#

Required Files#

.project/spec.yaml#

.project/configpack#

Optional Configuration Files#

Build Configuration Files#

Version Control Configuration#

Project Metadata and Registration#

Inventory Management#

Runtime Metadata Folder#

Project Lifecycle#

Project Creation#

Using the Desktop App#

Using the CLI#

Project Cloning#

Using the Desktop App#

Using the CLI#

Project Migration#

Configuration Details#

Project Naming#

Project Locations#

Build Behavior#

Desktop App#

CLI#

Examples#

Example 1: Minimal Python Project#

Example 2: Multi-Container Application#

Example 3: Custom Container Project#

Advanced Topics#

Spec.yaml Validation#

Project Portability#

Projects are portable across:#

Requirements for portability:#

Constraints and Limitations#

Project Name Constraints:#

Container Constraints:#

What Else is Covered?#

Related Topics#