jackin prewarm

Synopsis

jackin prewarm [--agent <NAME>]... [--sidecar] [--sidecar-container [--keep-sidecar-container] | --daemon] [--roles [--role <SELECTOR> [--role-git <URL>] | --workspace <NAME> | --all-workspaces]] [--image (--role <SELECTOR> [--role-git <URL>] | --workspace <NAME> | --all-workspaces | --all-roles) [--role-branch <BRANCH>]]

jackin prewarm fills jackin-owned runtime caches before a later launch asks for them. It prefetches agent runtime binaries and the matching jackin-capsule binary under ~/.jackin/ cache state. With --sidecar, it ensures the docker:dind sidecar image is present before a fresh launch needs to start a private Docker daemon; that sidecar-image check runs alongside binary cache warming instead of waiting until every runtime row has printed. With --sidecar-container, it starts a disposable docker:dind sidecar through the same network, image lookup/pull, TLS certificate, readiness, and cleanup path fresh launches use, waits until it is ready, prints the ready latency in milliseconds, then removes the container, network, and cert volume. Add --keep-sidecar-container to leave that explicitly prewarmed jackin-owned sidecar container, network, and cert volume running; a later fresh launch can acquire the prewarm-adoption lock, adopt the ready resources as a one-shot warm sidecar, and record the actual Docker resource names in the instance manifest so normal cleanup, eject, and purge remove them. --daemon is the shorthand daemon-oriented surface for that kept-sidecar path: it warms and keeps the private Docker daemon without running the separate standalone sidecar-image prewarm first, and records a PrewarmOnly diagnostics plan that names the skipped duplicate sidecar-image work. With --roles, it clones or updates configured role repos under ~/.jackin/roles/; add --role <SELECTOR> to target one role repo, --workspace <NAME> to target that saved workspace's default role repo, or --all-workspaces to target the default role repos used by saved workspaces. With --image, it also checks or builds derived Docker image tags for a role by running the same image recipe validity decision used by launch, emits a PrewarmOnly launch-plan diagnostic for reuse or rebuild, and warms the docker:dind sidecar image needed by a later fresh start. Add --all-roles to image-prewarm every configured role source without relying on saved workspace defaults.

It does not mutate workspaces, edit host git config, edit shell config, write gh config, or change agent configs outside jackin-owned state. Image prewarm may clone or update jackin-owned cached role repos under ~/.jackin/roles/, create temporary jackin-owned Docker build contexts, and run Docker builds when image labels are missing or stale. --sidecar-container creates only jackin-owned Docker resources and removes them before returning unless --keep-sidecar-container is passed explicitly; kept resources stay under jackin-owned Docker labels and are consumed by a later fresh launch rather than silently mutating host repos, git config, shell config, gh config, or agent configs.

From the jackin' workspace console, select a saved workspace and press W to run the same path as jackin prewarm --image --workspace <NAME>. The console exits before the prewarm command owns the terminal, so the operation has the same host-side effects and diagnostics as the CLI command.

Options

Option	Description
`--agent <NAME>`	Runtime binary to prewarm. Repeat to choose several. Defaults to all supported agents.
`--sidecar`	Pull the `docker:dind` sidecar image if Docker does not already have it locally. This lookup/pull overlaps with agent binary and `jackin-capsule` cache warming. It does not create a sidecar container, network, or cert volume.
`--sidecar-container`	Start a disposable `docker:dind` sidecar, wait for Docker/TLS readiness, print the measured ready latency, then remove the sidecar container, network, and cert volume. This implies the sidecar image lookup/pull.
`--keep-sidecar-container`	With `--sidecar-container`, keep the warmed jackin-owned sidecar container, network, and cert volume after readiness succeeds. A later fresh launch that acquires the prewarm-adoption lock can adopt those ready resources once, then normal instance cleanup owns them; concurrent launches that miss the lock start their own private sidecar.
`--daemon`	Shorthand for a kept sidecar-container prewarm. It starts the same private Docker daemon readiness path as `--sidecar-container --keep-sidecar-container`, leaves the jackin-owned resources running for one-shot launch adoption, and avoids the duplicate standalone sidecar image prewarm.
`--roles`	Clone or update role repos in jackin-owned cache state. With `--role`, only that role repo is prewarmed. With `--workspace` or `--all-workspaces`, jackin' targets saved-workspace default role repos without building images unless `--image` is also passed.
`--image`	Also prewarm derived Docker image(s) for a role and the `docker:dind` sidecar image needed by fresh starts. Valid local image labels are reused; missing or invalid recipes are rebuilt, and multiple selected agent image targets run concurrently while output stays sorted.
`--role <SELECTOR>`	Role selector for role-repo or image prewarm, such as `agent-smith` or `chainargos/backend-engineer`. Required with `--image` unless `--workspace` is provided. Optional with `--roles` to target one role repo.
`--workspace <NAME>`	Saved workspace whose default role repo or image should be prewarmed. With `--image`, if the workspace has a default agent, only that agent image is prewarmed unless `--agent` is repeated; otherwise jackin' prewarms every supported image for the role.
`--all-workspaces`	Prewarm every saved workspace that has a default role. With `--roles`, duplicate default role repos are updated once and refreshed concurrently while output stays sorted. With `--image`, eligible workspace image targets run concurrently while output stays sorted by workspace label; the command fails if none are eligible.
`--all-roles`	With `--image`, prewarm derived images for every configured role source. The command uses all supported agents for each role unless `--agent` is repeated.
`--role-git <URL>`	Git URL override for the role source. When omitted, jackin' uses the configured source for `--role`.
`--role-branch <BRANCH>`	Prewarm a branch-scoped role image. Uses the same branch-specific tag shape as `jackin load --role-branch`.

Agent names are claude, codex, amp, kimi, opencode, and grok.

Examples

# Prewarm all runtime binaries plus jackin-capsule
jackin prewarm

# Prewarm only the runtime you expect to launch next
jackin prewarm --agent claude

# Prewarm the DinD sidecar image used by fresh launches
jackin prewarm --sidecar

# Prewarm the disposable DinD startup/readiness path
jackin prewarm --sidecar-container

# Prewarm and keep a jackin-owned DinD sidecar running
jackin prewarm --sidecar-container --keep-sidecar-container

# Prewarm and keep a private Docker daemon for the next fresh launch
jackin prewarm --daemon

# Prewarm runtime binaries plus configured role repos
jackin prewarm --roles

# Prewarm runtime binaries plus one configured role repo
jackin prewarm --roles --role the-architect

# Prewarm runtime binaries plus one workspace default role repo
jackin prewarm --roles --workspace jackin

# Prewarm runtime binaries plus every saved workspace default role repo
jackin prewarm --roles --all-workspaces

# Prewarm one unconfigured role repo without building images
jackin prewarm --roles --role scratch --role-git https://github.com/acme/scratch-role.git

# Prewarm several runtimes
jackin prewarm --agent claude --agent kimi

# Reuse or build all derived images supported by a configured role
jackin prewarm --image --role the-architect

# Prewarm only one role image/runtime
jackin prewarm --image --role the-architect --agent codex

# Prewarm the image for a workspace's default role/agent
jackin prewarm --image --workspace jackin

# Prewarm images for every saved workspace with a default role
jackin prewarm --image --all-workspaces

# Prewarm images for every configured role
jackin prewarm --image --all-roles

# Prewarm a branch-specific role image
jackin prewarm --image --role the-architect --role-branch feat/my-pr

What it prepares

agent binary cache entries used by foreground image builds;
the jackin-capsule binary used by generated role images;
with --sidecar or --image, the docker:dind image used to start per-instance sidecars, warmed in parallel with the runtime binary cache work;
with --sidecar-container, a docker:dind container, network, and cert volume through the same readiness path used by fresh launches, removed before the command returns unless --keep-sidecar-container is passed; with --daemon, the same resources are kept for one-shot adoption by a later fresh launch;
with --roles, configured, targeted, or saved-workspace default role repos under ~/.jackin/roles/;
with --image, role-specific derived image tags for supported or selected agents, including every configured role when --all-roles is passed.

If a cached agent binary or jackin-capsule binary exists but has lost its executable bit, jackin' repairs that jackin-owned cache file, records agent_binary_cache_repaired or capsule_binary_cache_repaired diagnostics, and keeps prewarm on the local-cache path instead of redownloading the binary.

If an agent binary cannot be prefetched, the command reports a warning for that runtime. Later Docker builds can still fall back to the upstream installer for that agent.

What it does not prepare yet

The broader instant-launch roadmap still tracks host-daemon-maintained prewarm orchestration beyond this explicit CLI surface, richer launch-time adoption of persistent warm runtime resources, and plan-gated background refresh. See Instant Launch Architecture.