Volumes and Mounts

Why Volumes Matter

By default, each agent runs inside an isolated container with its own filesystem. Files created during a session live inside the container and remain accessible across sessions for that agent, but the agent cannot see files elsewhere on your computer.

Volumes (also called mounts) solve this by mapping a host folder to a path inside the container, giving the agent direct read/write access. This enables use cases like:

• Working on a code repository: mount a project folder so the agent can read, edit, and create files in the repo.
• Processing local documents: mount a folder of PDFs, spreadsheets, or data files for the agent to analyze.
• Sharing output files: the agent writes reports, generated code, or other artifacts directly to a folder accessible in Finder/Explorer.
• Collaborative workflows: multiple agents mount the same host folder to collaborate on shared files.

How Mounts Work

When a mount is added, Gamut records the mapping between a host path and a container path:

If multiple mounts share the same folder name, Gamut appends a numeric suffix to the container path (e.g., /mounts/myapp-2). The mount configuration is stored in a mounts.json file in the agent's data directory.

Adding a Mount

1. Open the agent's home page.
2. In the right panel, find the Volumes section.
3. Click Add Mount.
4. A system file picker opens. Select the folder to mount.
5. The mount appears in the volumes list.

Restarting After Changes

Adding or removing a mount while the agent is running requires a container restart to take effect. A notification banner appears:

Restart your agent for mount changes to take effect.

Click Restart to stop and restart the agent's container. If the agent is stopped, mount changes are picked up automatically on the next start.

Managing Mounts

Each mount row in the Volumes section shows the folder name, the full host path, and a health badge.

Health Status

Gamut checks whether the host path still exists each time the mount list loads:

• OK: the folder exists and is accessible.
• Missing: the folder has been moved, renamed, or deleted. The agent cannot access it.

Mount Actions

Hover over a mount row and click the three-dot menu:

• Open in Finder/Explorer: opens the host folder in the system file manager.
• Copy path: copies the host path to the clipboard.
• Remove Mount: detaches the folder from the agent. No files on the host are deleted; only the agent's access is removed.

Attachment Upload vs. Mounts

When a file or folder is attached to a message, Gamut asks how to handle it:

• Upload (copy): copies the file into the agent's container filesystem. Changes made by the agent do not affect the original file.
• Mount (direct access): adds the folder as a volume mount, giving the agent live read/write access to the original files.

Use uploads for one-off files the agent should reference. Use mounts for ongoing work where the agent reads and writes your actual project files.

Common Use Cases

Mounting a Code Project

Mount the repository root so the agent can navigate the full project structure, run tools, and make edits:

1. Add a mount pointing to the project directory (e.g., /Users/me/projects/myapp).
2. Restart the agent if it is running.
3. In the next message, reference files by their container path (e.g., /mounts/myapp/src/index.ts), or ask the agent to explore the mounted folder.

Mounting a Shared Data Folder

Mount a folder of input files (CSVs, logs, documents) and ask the agent to process them. Output files written to the same mount appear on the host machine immediately.

Multiple Mounts

An agent can have multiple mounts, each with its own container path under /mounts/. This is useful when an agent needs several independent directories (for example, a project folder and a reference documentation folder).