jackin load

Note

jackin load is the CLI entry point. For most day-to-day work, jackin 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.

Synopsis

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, a workspace default_agent wins first, a single-agent role uses its only runtime, and a multi-agent role prompts interactively. A non-interactive launch (no TTY) against a multi-agent role with no resolved choice errors out.

Examples

# 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)
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)
5. Resolves the runtime agent from --agent, workspace default_agent, a single supported role agent, or an interactive prompt for multi-agent roles
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

Note

Host-side Docker work follows the operator’s selected Docker daemon. If DOCKER_HOST is set to a non-empty value, jackin’ uses it. Otherwise jackin’ follows the active Docker CLI context (honouring a per-shell DOCKER_CONTEXT override) for local-socket and plain HTTP/TCP contexts, so the image build, per-agent network, DinD sidecar, and role container are created on the same Docker backend. SSH and TLS Docker contexts currently fail with an explicit error instead of silently dropping connection settings.

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.

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

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.

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.

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.

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.

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.

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

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