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.

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.

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)

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.

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.

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 from the host repo’s current branch. The container has its own .git/ and independent refs; when the host repo has an origin, pushes from the container publish to that remote.

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.

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.

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.

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.

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.