Mounts

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❯ security model: agents can only access what you explicitly mount.

Mount spec format

The --mount flag accepts two formats:

Same-path mount

--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

--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:

--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:

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:

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:

# 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:

# 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:

# 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

# 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)

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 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.

Set isolation per mount with --mount-isolation <dst>=<type> on jackin workspace create and jackin workspace edit. See Per-mount isolation in the workspaces guide for the full validation rules and recommended patterns.

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.

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.