AI Workbench Mounts

Overview of Mounts

Container isolation from the host environment relies separation from the host file system. This separation is necessary but can be inconvenient, for example when:

• You want to share or move files between the host and the container.

• Large files in the container inhibit ability to move the container to a different host.

Mounts are a container feature that provides a controlled way to reduce separation between the container and the host file systems. You can read more about them here.

Workbench manages mounts consistently across different hosts, runtimes, and users.

• You can create them directly in the Workbench UI, Desktop App or CLI.

• Mount metadata is written to the spec.yaml file and and is versioned with the project.

• Workbench automatically configures the mounts when the project moves to a different host, runtime, or user.

• Source directories for mounts are configurable on a per host and per user basis.

• You can set mount options, like read-only.

Note

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

Table of Mount Types and Basic Usage

Workbench uses the basic mount primitives available to Docker and Podman.

Table of Mount Types

Mount Type	Versioned	Named	Target in Container	Source on Host	Configurable	Description
project	Yes	Yes	Yes	Yes	No	Defines where the project repository on the host is mounted in the project container. Set to /project/ by default.
host	No	Yes	Yes	Yes	Yes	Mounts an existing directory from the host machine into the project container.
volume	No	Yes	Yes	No	Yes	Creates a persistent volume for storing data that is not erased when the project container is stopped or re-built.
temp	No	Yes	Yes	No	Yes	Creates a temporary folder in the project container that is reset every time the container is started.

Target Directories vs. Source Directories

Target directories are in the container file system where you want the files to appear.

• They are not versioned.

• They are used for all mount types.

• They are unique and do not change if the project moves between hosts, runtimes or users.

Source directories are on the host file system.

• They are not versioned.

• They are only used for host mount types.

• They may change if the project moves between hosts, runtimes or users.

Basic Usage for Mounts

The easiest way to create and manage mounts is through the Desktop App. If you need to script mount creation and management, you can use the CLI.

• Configure a mount in Project Tab > Project Container > Mounts > Add.

• Select the mount type and give it a name. Descriptions are optional.

• Enter the target directory. You must use absolute file paths within the container, starting with /.

• (if host mount type) Enter the source directory. You must use absolute file paths on the host.

• Start or re-start the container for changes to take effect.

Warning

Do not put mount targets into versioned directories, e.g. /project/. It will cause errors or unexpected behavior.

Details and Usage for Mount Types

The Project Mount

This mount is created automatically by Workbench and it is the main directory managed by Workbench.

• There can only be one per project.

• It is versioned.

• The source directory on the host is the project repository.

• The target directory in the container is /project/.

Host Mount Usage

These mounts are created by the user and are for sharing files between the host and the container.

• They are not versioned.

• You must give it a unique name. Descriptions are optional.

• You must enter a target directory in the container. It should not be a sub-directory of a versioned directory, e.g. /project/.

• You must enter a source directory on the host. The source directory must exist before the mount is created.

Host mounts have some technical differences between Podman and Docker across macOS, Windows, and Linux.

Host mounts can run into issues stemming from trying to resolve different users and permissions between the host and the container. These issues typically appear when the container is built.

To ensure host mounts work as expected on different hosts and runtimes, always make sure the target directory exists in the project container prior to creating the Host mount.

The easiest way to do this is to use the postInstall.bash script and add something like:

sudo mkdir -p /mnt/my-host-mount
sudo chmod workbench:workbench /mnt/my-host-mount

If you are using a container that uses a different user than workbench you may need to adjust this command.

Properly configured host mounts will have consistent behavior between different hosts, runtimes, and users.

• Mount names and target directories are not changed if the project is moved between hosts, runtimes, or users.

• Source directories may be changed if the project is moved between hosts, runtimes, or users.

Volume Mount Usage

These mounts are created by the user and are for persisting files between container sessions.

• They are not versioned.

• You must give it a unique name. Descriptions are optional.

• You must enter a target directory in the container. It should not be a sub-directory of a versioned directory, e.g. /project/.

Temp Mount Usage

These mounts are created by the user and are for writing files that are not needed after the container is stopped.

• They are not versioned.

• You must give it a unique name. Descriptions are optional.

• You must enter a target directory in the container. It should not be a sub-directory of a versioned directory, e.g. /project/.

FAQs

Common questions on mounts

When should I use a host mount?

The following are hypothetical examples.

• You have local files that you want to use in the container but you don’t want versioned. If you want those files protected from changes, you can set the mount to be read-only.

• You are working in two locations, each of which has a common set of static files that you don’t want to store on a Git remote.

• You have an NFS mount that you want to use in the container.

When should I use a volume mount?

The following are hypothetical examples.

• You are creating data products that need to persist when the container is stopped or restarted but don’t want versioned.

• You want to share data between different projects.

When should I use a temp mount?

The following are hypothetical examples.

• Something in your development environment (command or application) creates a large number of files that you only need for a given session.

Can I use the CLI to create and configure mounts?

Yes. The CLI has the same functionality as the Desktop App for creating and configuring mounts.

• Open the terminal and activate the desired context (location)

• Run nvwb open <project-name> to open the project you want to add the mount to

• Run nvwb create mount

  • Select the mount type

  • Enter the target directory

  • Enter an optional description

  • Enter mount options, if any

  • Hit enter

This will automatically create volume and temp mounts. However, creating a host mount requires you to add a source directory as follows:

• Run nvwb configure mounts.

  • Select the target directory to configure.

  • Enter the absolute path to the source directory.

  • Hit enter

Deleting a Mount

• Open the terminal and activate the desired context (location)

• Run nvwb open <project-name> to open the project from which you want to delete the mount

• Run nvwb delete mount

• Select the mount to delete. You are not prompted for confirmation

Next Steps

• Hardware