---
title: jackin load
description: "Jack an agent into an isolated container"
---
import { Aside } from '@astrojs/starlight/components'

<Aside type="note">
`jackin load` is the **CLI** entry point. For most day-to-day work,
[`jackin console`](/commands/console/) is simpler and faster. Use
`jackin load` when you want a scriptable one-liner, want to skip the
TUI entirely, or want a flag the console does not expose.
</Aside>

## Synopsis

```bash
jackin load [SELECTOR] [TARGET] [OPTIONS]
```

Load an agent into an isolated `Docker` container directly from the command line.

`SELECTOR` chooses the **role** (tool profile). `TARGET` chooses the **workspace or path** (file access boundary).

## Arguments

| Argument | Required | Description |
|---|---|---|
| `SELECTOR` | No | Role selector (e.g., `agent-smith`, `chainargos/backend-engineer`). When omitted, uses the last-used or default role for the workspace. |
| `TARGET` | No | Path, `path:container-dest`, or saved workspace name. Defaults to the current directory. |

## Options

| Option | Description |
|---|---|
| `--mount <SPEC>` | Additional bind-mount spec. Repeatable. Format: `path[:ro]` or `src:dst[:ro]` |
| `--rebuild` | Force rebuild the Docker image and refresh agent CLI install layers |
| `--role-branch <BRANCH>` | Check out a specific branch of the role repository for local testing. See **Testing a role branch** below. |
| `--force` | Acknowledge a dirty host working tree when materializing an isolated mount in non-interactive mode. Required only when (a) the workspace has at least one `worktree`-isolated mount and (b) the host repo's tree has staged, unstaged-tracked, or untracked files. Ignored otherwise. |
| `--no-intro` | Skip the animated intro sequence |
| `--debug` | Print raw container output for troubleshooting |
| `--agent <NAME>` | Override the launch agent (`claude`, `codex`, `amp`, `kimi`, or `opencode`). When omitted on a multi-agent role with no `default_agent` on the workspace, an interactive prompt asks. |

## Examples

```bash
# Use workspace + last agent for current directory
jackin load

# Force fresh agent CLI install layers
jackin load --rebuild

# Load a specific agent into current directory
jackin load agent-smith

# Load into a specific path
jackin load agent-smith ~/Projects/my-app

# Path with custom container destination
jackin load agent-smith ~/Projects/my-app:/app

# Load into a saved workspace
jackin load agent-smith big-monorepo

# Workspace with additional mounts
jackin load agent-smith big-monorepo --mount ~/extra-data

# Path with read-only additional mount
jackin load agent-smith ~/app --mount ~/cache:/cache:ro

# Build and test a specific role branch locally before it merges
jackin load the-architect --role-branch feat/my-pr
```

## What happens

1. Resolves the role and clones/updates its repository (or the specified branch when `--role-branch` is set)
2. Validates the role repo contract (`jackin.role.toml` + Dockerfile) with strict manifest parsing
3. **If the agent source has never been trusted**, prompts the operator to review and confirm before proceeding (see [Agent source trust](/guides/security-model#4-agent-source-trust))
4. **If `--role-branch` is set**, always prompts to confirm the branch is safe to build, regardless of the role's trust status (see [Branch trust gate](/guides/security-model#branch-trust-gate))
5. **If the role supports multiple agents** and neither `--agent` nor a workspace `default_agent` is set, prompts to choose the agent runtime
6. Checks resolved mounts for sensitive host paths (`~/.ssh`, `~/.aws`, etc.) and prompts for confirmation if any are detected
7. Prompts for interactive environment variables declared in the manifest
8. Generates and builds a derived Docker image, including declared Claude plugins (cached if unchanged; branch builds ignore `published_image` and always build from source)
9. Checks the local instance index for missing recoverable work in the same workspace or directory before creating a fresh runtime; matching-role restore candidates can be rebuilt from the prompt, and related role instances whose containers are gone can be recovered or rebuilt in place from the saved manifest source/ref. Running or stopped instances do not block a fresh launch.
10. Creates a per-agent Docker network and DinD sidecar
11. Launches the agent container with all resolved mounts and environment variables
12. Runs runtime hooks if declared (`setup_once`, `source`, then `preflight`)
13. Starts the selected agent CLI

<Aside type="note">
If the agent manifest declares interactive environment variables, `jackin load` prompts for their values before building the Docker image. This ensures no build time is wasted if you cancel.
</Aside>
<Aside type="caution">
Third-party agents (namespaced selectors like `org/agent-name`) require trust confirmation on first use. jackin' will show the agent name and git URL and ask you to confirm before building. You can pre-trust with `jackin config trust grant org/agent-name` or revoke with `jackin config trust revoke org/agent-name`. See [Agent source trust](/guides/security-model#4-agent-source-trust) for details.
</Aside>
<Aside type="note">
If the cached role repo has been locally modified, contains extra files, or its git `origin` no longer matches the configured source, `jackin load` stops with an error instead of trusting that cache.
</Aside>
<Aside type="caution">
If two resolved mounts target the same container destination, `jackin load` fails with a conflict error. It does not silently override one mount with another.
</Aside>
<Aside type="tip">
If no selector is given and the current directory falls under a saved workspace's host `workdir` or one of its mounted host paths, that workspace's default or last-used agent is used automatically.
</Aside>
## Testing a role branch (`--role-branch`)

`--role-branch` lets you build and run a specific branch of a role repository locally before it merges to the default branch. This is the intended workflow for verifying a PR on a role repo (for example, checking that a Dockerfile change works end-to-end) without affecting your stable local image or other operators who may share the same role.

```bash
jackin load the-architect --role-branch feat/caveman-all-install
```

### What changes when `--role-branch` is set

| Behaviour | Default | With `--role-branch` |
|---|---|---|
| Branch cached and reused | Default branch | The named branch — repeat loads of the same branch reuse the cached checkout |
| Image | Stable per-role image | Branch-specific image, fully isolated from the stable image |
| Concurrency with default-branch loads | Same role's default-branch load may be blocked while the cache refreshes | Branch builds never block default-branch loads, and vice versa |
| Trust confirmation | First-use only | **Always** — regardless of the role's trusted status |
| Forced rebuild | Pass `--rebuild` to refresh layers | Same — pass `--rebuild` to refresh layers |

The branch image is completely separate from the default-branch image. Running `jackin load the-architect` after a branch build still uses the unchanged default-branch image.

Branch names with slashes (`feat/my-pr`) and dashes (`feat-my-pr`) are kept distinct, so loading both never reuses the same image or cache slot by mistake.

For choosing between a fresh instance and another agent session inside an existing instance, see [Parallel Agents](/guides/parallel-agents/).

### Branch trust gate

Every `--role-branch` load triggers an interactive confirmation, even for roles you have already trusted:

```
!! Unreviewed branch — verify before proceeding !!

  role:   the-architect
  source: https://github.com/jackin-project/jackin-the-architect.git
  branch: feat/caveman-all-install

  This branch has not been merged to the default branch.
  Its Dockerfile and scripts may differ from the trusted main branch.
  A malicious contributor could introduce harmful code that runs
  on your machine during the image build.

  Review the branch diff in the role repository before continuing.

Have you reviewed branch "feat/caveman-all-install" and verified it is safe to build? [y/N]
```

This gate exists because `trusted = true` in your config covers the default branch of a role, not every PR branch an external contributor might open against it. See [Branch trust gate](/guides/security-model#branch-trust-gate) for the full threat model.

`--role-branch` requires an interactive terminal. Non-interactive contexts (CI, scripts) will exit with an error — this is intentional.

### Combining with `--rebuild`

`--role-branch` alone does not bust the Docker layer cache. If you push new commits to the branch and want a clean rebuild:

```bash
jackin load the-architect --role-branch feat/my-pr --rebuild
```

## Dirty-host acknowledgement (`--force`)

When a workspace mount has `isolation = "worktree"`, `jackin load` materializes a new `git worktree` from the host repo's current `HEAD` before starting the container. If the host tree is dirty (staged changes, unstaged tracked changes, or untracked files — ignored files do not count), those edits stay on the host and are **not** carried into the agent's worktree.

In an interactive shell jackin' prompts you to confirm before materializing. In non-interactive contexts (CI, scripts, piped input) the launch fails fast unless you pass `--force` to acknowledge that:

- the worktree branches from `HEAD`, not from your working copy
- uncommitted host edits will not appear inside the container

`--force` does **not**:

- discard, stash, or commit any host changes
- relax any other validation (sensitive mounts, mid-rebase host repo, readonly worktree mounts, nested isolated dst paths still hard-error)
- affect `shared` mounts or workspaces with no isolated mounts
