---
title: Mounts
description: Control which directories agents can access and how
---
import { Aside } from '@astrojs/starlight/components'


## How mounts work

Mounts are the primary mechanism for giving agents access to your files. When you mount a directory, it appears inside the agent's container at the path you specify. Without a mount, the agent simply can't see that directory.

This is the core of jackin's security model: **agents can only access what you explicitly mount.**

<Aside type="tip">
Workspace mounts are managed through `jackin workspace …` flags or
the operator console's workspace editor. **Global mounts** (the
`jackin config mount` family) can also be managed from the console's
**Global config → Global mounts** screen. Either way, you should not
need to hand-edit a configuration file to add, remove, or change a mount.
</Aside>

## Mount spec format

The `--mount` flag accepts two formats:

### Same-path mount

```bash
--mount ~/Projects/my-app
```

Mounts `~/Projects/my-app` to the **same absolute path** inside the container. This is the most common pattern — it keeps file paths consistent between your host and the agent.

### Explicit source and destination

```bash
--mount ~/Projects/my-app:/workspace
```

Mounts `~/Projects/my-app` on your host to `/workspace` inside the container. Use this when you want a different layout inside the container.

### Read-only mounts

Append `:ro` to make a mount read-only:

```bash
--mount ~/reference-docs:/docs:ro
--mount ~/Projects/shared-lib:ro
```

Read-only mounts let the agent read files but prevent any modifications. Use this for:
- Reference codebases the agent should read but not change
- Shared libraries or documentation
- Configuration files you want to expose but protect

## Types of mounts

### Load-time mounts

Pass `--mount` when loading an agent:

```bash
jackin load agent-smith --mount ~/data:/data:ro
```

These mounts are one-time — they apply only to this specific container launch.

### Workspace mounts

Save mounts as part of a workspace definition:

```bash
jackin workspace create my-app \
  --workdir ~/Projects/my-app \
  --mount ~/Projects/my-app \
  --mount ~/cache:/cache:ro
```

Workspace mounts apply every time you load an agent into that workspace. You can combine them with load-time mounts:

```bash
# Workspace mounts + additional load-time mount
jackin load agent-smith my-app --mount ~/extra-data:/extra
```

### Global mounts

Global mounts apply to every agent launch. Use them for directories you always want available:

```bash
# Mount your Gradle cache for all agents
jackin config mount add gradle-cache \
  --src ~/.gradle/caches \
  --dst /home/agent/.gradle/caches \
  --readonly
```

### Scoped global mounts

Scope a global mount to specific roles:

```bash
# Only mount secrets for chainargos roles
jackin config mount add secrets \
  --src ~/.chainargos/secrets \
  --dst /secrets \
  --readonly \
  --scope "chainargos/*"
```

The `--scope` flag supports glob patterns:
- `"chainargos/*"` — matches all roles in the chainargos namespace
- `"chainargos/backend-engineer"` — matches only a specific role

### Managing global mounts

```bash
# List all global mounts
jackin config mount list

# Remove a global mount
jackin config mount remove gradle-cache
```

In the console, press `G` from the workspace list to open **Global config → Global mounts**. That screen lists every global mount with its name, source, destination, mode, scope, and source type. It supports adding mounts, editing source and destination, toggling read-only mode, changing scope, renaming, and removing mounts. Changes stay pending until you explicitly save the global config; workspace screens never write global mounts.

Workspace views show global mounts separately from workspace mounts. When jackin can determine the selected role for a workspace, role-scoped global mounts are included in the global section. When multiple roles are possible, workspace views explain that the selected role affects global mount visibility.

## Mount precedence

When multiple mount sources are resolved, jackin' combines them in this order:

1. **Global mounts** (from `jackin config mount`)
2. **Workspace mounts** (from `jackin workspace create`)
3. **Load-time mounts** (from `jackin load --mount`)

<Aside type="caution">
If two mounts target the same container destination, jackin' stops with an error. It does not silently let the later mount win. This is deliberate because mounts are part of the security boundary.
</Aside>

## Redundant mounts

A saved workspace never contains two mounts where one already exposes the other's host subtree at the same container location. If you add a mount that strictly covers an existing one, jackin' detects the redundancy:

- `jackin workspace create` automatically removes the redundant mount and prints a summary.
- `jackin workspace edit` prompts before collapsing — see the [`workspace edit` docs](/commands/workspace/#mount-collapse) for the prompt and the `--yes` / `--prune` flags.

Identity mounts (same source AND same destination) are not redundant — they are simply replaced in place.

Ad-hoc `--mount` flags passed at launch time are kept literal and are not collapsed against workspace mounts.

## Mount isolation

Workspace mounts can be marked **isolated** so that each container gets its own per-container git checkout instead of sharing the host directory directly. This is what lets you run multiple agents against the same project at the same time without them stepping on each other.

| Value | Behavior |
|---|---|
| `shared` (default) | Host path bind-mounted as-is. |
| `worktree` | jackin' creates a per-container `git worktree` from the host repo. The container sees its own checkout and scratch branch; refs are shared with the host repo. |
| `clone` | jackin' creates a per-container `git clone --local`. The container has its own `.git/` and independent refs. |

Set isolation per mount with `--mount-isolation <dst>=<type>` on `jackin workspace create` and `jackin workspace edit`. See [Per-mount isolation](/guides/workspaces/#per-mount-isolation) in the workspaces guide for the full validation rules and recommended patterns.

<Aside type="note">
Isolation is a workspace-mount concept only. Global mounts (added with
`jackin config mount add`) are typically non-repo system paths, so
`shared` is always the answer there — passing isolation flags to
global mounts is rejected.
</Aside>

## Sensitive path warnings

jackin' detects when a mount source matches a known sensitive directory and warns before proceeding:

- `~/.ssh` — SSH keys and configuration
- `~/.aws` — AWS credentials and configuration
- `~/.gnupg` — GPG keys and trust database
- `~/.config/gcloud` — Google Cloud credentials
- `~/.kube` — Kubernetes credentials and configuration
- `~/.docker` — Docker credentials and configuration

When a sensitive path is detected, you'll see a warning explaining the risk and must confirm before the mount is applied. This applies to all mount types — load-time, workspace, and global mounts.

<Aside type="caution">
The warning defaults to "no". If stdin is not a terminal (e.g. in a script), jackin' aborts rather than silently mounting sensitive paths.
</Aside>

## Best practices

- **Mount only what the agent needs.** Don't mount your entire home directory. Be specific about which project directories the agent should access.
- **Use read-only when possible.** If the agent only needs to read reference code or configuration, mount it as `:ro`.
- **Use global mounts for caches.** Things like Gradle caches, npm caches, or Maven repositories are great candidates for global read-only mounts — they speed up builds inside the container.
- **Keep paths consistent.** When possible, use same-path mounts so that file paths in the agent's output match your host paths.
