AI Workbench Projects

An AI Workbench project contains everything you need to do your work: code, data, models, environment configuration, metadata, and work history.

Overview of Workbench Projects

Projects are Git Repositories

AI Workbench projects are structured just like Git repositories with extra information. They are similar in the following ways:

• They have a few extra files that provide metadata that drive automation and the overall user experience.

• Any Git repository can be an AI Workbench project by adding the correct files.

• Projects necessarily imply a containerized development environment, i.e. the project container.

• Projects necessarily imply Git versioning (git vs git-lfs vs git-ignore) for individual files and folders.

AI Workbench Makes Projects Portable and Reproducible

AI Workbench allows you to create projects that are portable and reproducible in the following ways:

• Workbench handles the Git and container commands to build, run, and version the project.

• The trade-off is that you have to be let the Desktop App or CLI command-line interface handle actions such as git clone or docker run.

Your portable and reproducible projects are only as good as the system you are running them on and that you have properly configured your SSH keys, API keys, or other secrets. To keep your projects portable and reproducible, you should:

• Ensure the system you are running the project on has the correct minimum required hardware (GPUs, etc.) to run the project.

• Ensure you have any SSH keys, API keys, or other secrets, properly configured in your AI Workbench project.

Note

The best way to understand how projects work is to work through the exercises in the Onboarding Project.

The Default AI Workbench Project File Structure

AI Workbench projects are specially-formatted Git repositories. When you create a new project, AI Workbench creates it and structures the filesystem just like it was a Git repository. These files together represent the AI Workbench project.

Use the project filter bar to filter your file browser view. To duplicate, edit, rename, or delete a file, right-click it and select either Duplicate, Edit, Rename, or Delete. You can also select these commands from the … menu on the right.

Note

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

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 Packages.	No.	Yes.
postBuild.bash	Runs after installing packages. Runs as the container user with passwordless sudo access. For more information, see Scripts.	No.	Yes.
preBuild.bash	Runs before installing packages. Runs as the container user with passwordless sudo access. For more information, see Scripts.	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 Packages.	No.	Yes.
variables.env	Non-sensitive environment variables set in the container at runtime. Variables are not built into the container image. For more information, see Environment Variables.	No.	Yes.

AI Workbench Projects and Git

We recommend that you don’t commit intermediate data, or other large files that you can easily recreate, to avoid bloating your Git repository. You can use the data/scratch directory, which is ignored by Git, to store temporary data. You can also create your own directory for this purpose and add it to the .gitignore file.

AI Workbench automatically warns you when large files are about to be tracked by Git. You can move the files to an untracked ___location, to a Git LFS tracked ___location, or delete them altogether. Git LFS tracked locations are listed in the .gitattributes file.

For more information, see Git in AI Workbench.

Persist Data Between Container Restarts

When you work in a container, files written to the container’s filesystem do not persist when you restart the container. AI Workbench removes containers when they stop, which means that any changes you make to the container are lost.

To persist project data between restarts, use a mount. A mount allows you to persist data even after the container is stopped or removed. A host mount binds a directory from your host computer into the container. A volume mount creates a Docker/Podman volume to store data.

For more information, see AI Workbench Mounts.

Note

By default, each project has a project mount for the container so that changes you make to project code itself (like postBuild.bash) persist across container restarts.

FAQs

Can I manage projects using the CLI?

Yes. The CLI has feature parity with the Desktop App.

Next Steps

• The Project Specification
• Single Container Environments
• Multi-Container Environments
• BYOC