jackin load

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

Every invocation gets a run diagnostics handle such as 42f9aa. jackin load requires a rich terminal and shows a full-screen launch progress surface with a sliding stage rail for jackin❯ stages (identity, role, credentials, construct, agent binaries, derived image, workspace, network, sidecar, capsule, hardline). The stage-word row below the rail fades at both ends as it scrolls, so clipped words taper in and out instead of cutting off abruptly. Workspace repository polling from git_pull_on_entry is part of that surface; per-repo pull details go to diagnostics/debug evidence instead of printing over the launch cockpit. Prompts for role choice, target ambiguity, sensitive mounts, role trust, restore decisions, agent choice, and manifest env values render as launch dialogs instead of plain terminal prompts.

The full digital rain animation is a boundary marker. The intro is two screens — the opening phrase/logo screen, then the accelerating warp into the construct — and appears only when this launch starts with no jackin-managed role containers already running. The outro is two screens too — the decelerating warp, then the closing logo/time-in-construct caption — and appears only when the foreground session exits and no role containers remain. Launching or leaving a second concurrent instance does not play either boundary ritual because the operator is still inside the construct. Non-interactive shells and terminals that cannot host the rich surface cannot run jackin load; use jackin console from a rich terminal or fix the terminal environment.

Contributors can force the boundary rituals for local visual QA with env vars instead of CLI flags. See Launch Progress Surface for JACKIN_FORCE_BOUNDARY_INTRO, JACKIN_FORCE_BOUNDARY_OUTRO, and JACKIN_FORCE_BOUNDARY_RITUALS.

Arguments

Options

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. Resolves operator env, then prompts for any remaining interactive environment variables declared in the manifest
8. Resolves and caches the required agent binaries and the matching jackin-capsule binary under jackin-owned host cache state
9. Generates and builds a derived Docker image, including declared Claude plugins (cached if unchanged; branch builds ignore published_image and always build from source)
10. 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.
11. Creates a per-agent Docker network and DinD sidecar
12. Launches the agent container with all resolved mounts and environment variables
13. Runs runtime hooks if declared (setup_once, source, then preflight)
14. Starts the selected agent CLI

Failures in the launch surface show a short diagnosis, the failed stage, the diagnostics run handle, and evidence paths under jackin-owned state. Raw Docker output, build logs, stack traces, and debug traces are not rendered in the failure popup. The live Docker build overlay uses a black terminal-style surface and interprets ANSI colour from Docker output when present. The run timeline remains JSONL for agent/debug analysis; Docker build failures also write a plain, colour-free .log sidecar with the command, working directory, exit status, stdout, and stderr so the operator can inspect the Docker output directly from a terminal.

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

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 rich confirmation dialog, even for roles you have already trusted. The dialog names the role, source URL, and branch, then requires you to confirm that you reviewed the branch before jackin❯ builds it.

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 rich launch, jackin❯ asks for confirmation in the launch dialog 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