Configuration File

Storage locations

Environment overrides

Three environment variables redirect these default storage roots without touching any TOML config, useful for testing a PR in isolation or running multiple independent configurations side by side:

Setting JACKIN_CONFIG_DIR and JACKIN_HOME_DIR to fresh directories before running jackin❯ means every command reads and writes only those directories, leaving the live operator state completely untouched. Unset behavior is identical to not setting the variables — jackin❯ falls back to the defaults above.

One file per workspace, by design

Saved workspaces live one-per-file under ~/.config/jackin/workspaces/ rather than as [workspaces.<name>] tables inside a single config.toml. The layout works directly with a dotfile manager like chezmoi tracking ~/.config/jackin/. Operators commonly want to:

• Version-control selectively — track config.toml globally, include only team-relevant workspace files, leave the rest out via .gitignore, or keep workspaces private per-machine.
• Restore the full setup on a new machine by checking out the dotfile repo and running chezmoi apply (or equivalent), with no manual TOML reconstruction.
• Diff a single workspace in PR review without seeing churn in unrelated workspaces, which is impossible when every change touches a shared [workspaces.*] block.

Each file carries its own version = "v1alpha8" stamp, so a dotfile-managed setup that is partially old (some workspaces stamped, some not) migrates per-file on first load. See Schema Versions for the full version history and migration matrix.

config.toml schema

The configuration is TOML. Global settings live at ~/.config/jackin/config.toml; saved workspaces live one-per-file under ~/.config/jackin/workspaces/. The CLI and console manage both locations for you, so you generally don't need to edit them by hand.

Top-level version is the config schema version. jackin❯ writes version = "v1alpha8" today. Older config files with no version are treated as legacy and migrated automatically on startup before parsing. See Schema Versions for the full version history and migration matrix.

Runtime backend selection

[runtime] selects the container backend used for fresh launches. The global config.toml field is default_backend; a workspace file can override it with backend.

# ~/.config/jackin/config.toml
[runtime]
default_backend = "docker"  # "docker" (default) or "apple-container"

# ~/.config/jackin/workspaces/my-app.toml
[runtime]
backend = "docker"          # override the global default for this workspace

docker is the stable Docker + DinD backend. apple-container routes launch to Apple's container CLI on supported macOS hosts, but it is still an experimental Phase 0 backend: launch selection, manifest state, and lifecycle dispatch are wired, while full hardware validation and finalization parity are still tracked on the Apple Container backend roadmap.

Role repo refresh

Launch-time role repo refreshes are cached briefly to keep repeated loads from blocking on a network git fetch when the cached repo was just refreshed:

role_repo_refresh_ttl_seconds = 60

When the field is absent, jackin❯ uses 60 seconds. Set it to 0 to fetch on every launch, matching the pre-existing behavior. jackin load --rebuild, explicit branch overrides, and background image refresh/prewarm paths always fetch rather than using the TTL shortcut.

Agent auth-forward settings

auth_forward is configured per agent (claude, codex, amp, kimi, opencode, grok) at three layers, with most-specific wins:

version = "v1alpha8"

# Layer 1 — global default (per agent)
[claude]
auth_forward = "sync"  # "sync" (default), "api_key", "oauth_token", or "ignore"
sync_source_dir = "/Users/operator/.claude-work"

[codex]
auth_forward = "sync"  # "sync" (default), "api_key", or "ignore" — Codex rejects "oauth_token"

[amp]
auth_forward = "sync"  # "sync" (default), "api_key", or "ignore" — Amp rejects "oauth_token"

[kimi]
auth_forward = "sync"  # "sync" (default), "api_key", or "ignore" — Kimi rejects "oauth_token"

[opencode]
auth_forward = "sync"  # "sync" (default), "api_key", or "ignore" — OpenCode rejects "oauth_token"

[grok]
auth_forward = "sync"  # "sync" (default), "api_key", or "ignore" — Grok rejects "oauth_token"

# Layer 2 — workspace-wide override
[claude]
auth_forward = "oauth_token"

[codex]
auth_forward = "api_key"

[amp]
auth_forward = "api_key"

[kimi]
auth_forward = "sync"

[opencode]
auth_forward = "sync"

[grok]
auth_forward = "sync"

# Layer 3 — most-specific (workspace × role × agent) override
[roles.agent-smith.claude]
auth_forward = "ignore"
sync_source_dir = "/Users/operator/.claude-smith"

[roles.agent-smith.codex]
auth_forward = "sync"

[roles.agent-smith.amp]
auth_forward = "ignore"

[roles.agent-smith.kimi]
auth_forward = "sync"

[roles.agent-smith.opencode]
auth_forward = "sync"

[roles.agent-smith.grok]
auth_forward = "api_key"

The layer 2 and 3 examples above belong in ~/.config/jackin/workspaces/my-app.toml; the global defaults belong in config.toml.

Accepted values: sync | api_key | oauth_token | ignore. oauth_token is Claude only — setting it under any [codex], [amp], [kimi], [opencode], or [grok] block is rejected at parse time.

Locations the field may appear at, in resolution order (most-specific first):

• [roles.<role>.claude].auth_forward in workspaces/<ws>.toml
• [roles.<role>.codex].auth_forward in workspaces/<ws>.toml
• [roles.<role>.amp].auth_forward in workspaces/<ws>.toml
• [roles.<role>.kimi].auth_forward in workspaces/<ws>.toml
• [roles.<role>.opencode].auth_forward in workspaces/<ws>.toml
• [roles.<role>.grok].auth_forward in workspaces/<ws>.toml
• [claude].auth_forward in workspaces/<ws>.toml
• [codex].auth_forward in workspaces/<ws>.toml
• [amp].auth_forward in workspaces/<ws>.toml
• [kimi].auth_forward in workspaces/<ws>.toml
• [opencode].auth_forward in workspaces/<ws>.toml
• [grok].auth_forward in workspaces/<ws>.toml
• [claude].auth_forward (global default)
• [codex].auth_forward (global default)
• [amp].auth_forward (global default)
• [kimi].auth_forward (global default)
• [opencode].auth_forward (global default)
• [grok].auth_forward (global default)

Credentials referenced by api_key and oauth_token live in ordinary [*.env] blocks under the well-known names ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, OPENAI_API_KEY, AMP_API_KEY, and KIMI_API_KEY, OPENCODE_API_KEY, and XAI_API_KEY. Grok api_key mode also exposes the configured key as GROK_DEPLOYMENT_KEY inside the container so the Grok CLI can use either personal or deployment-key auth.

The workspace editor stages Auth-tab edits in memory until the operator confirms the workspace save. The save path in crates/jackin/src/console/services.rs applies separate diff passes for general workspace fields, agent auth modes, agent sync source folders, and credential env values; the sync-source pass writes through ConfigEditor setters in crates/jackin-config/src/editor.rs for both workspace and role layers. This keeps the dialog staging model consistent: the Auth dialog changes pending state only, and disk writes happen only after the workspace save confirmation.

GitHub CLI auth-forward settings

GitHub CLI (gh) auth uses a parallel [github] block with three modes — sync (default), token, ignore. The [github] axis has no agent dimension because ~/.config/gh/ is shared by every agent in the container.

# Layer 1 — global default
[github]
auth_forward = "sync"   # "sync" (default), "token", or "ignore"

# Layer 2 — workspace-wide override (e.g. a customer-facing PAT)
[github]
auth_forward = "token"

[github.env]
GH_TOKEN = { op = "op://abc.../def.../fld...", path = "Work/ACME/github-fine-grained-pat" }

# Layer 3 — workspace × role override (e.g. a tighter release-bot token)
[roles.release-bot.github]
auth_forward = "token"

[roles.release-bot.github.env]
GH_TOKEN = { op = "op://abc.../def.../fld...", path = "Work/ACME/github-release-pat" }

# Per-role opt-out — throwaway role with no GitHub access
[roles.scratch.github]
auth_forward = "ignore"

Workspace-scoped GitHub blocks live in ~/.config/jackin/workspaces/customer-acme.toml.

Mode behaviour:

• sync — materialize ~/.config/gh/hosts.yml from the host's gh login on each launch (gh auth token --hostname github.com, with ~/.config/gh/hosts.yml parse as a fallback). When the host is logged out, any existing in-container hosts.yml is preserved.
• token — wipe any prior hosts.yml and inject GH_TOKEN (and GITHUB_TOKEN from the same source) into the container's process env from the resolved [github.env] map. Pre-flight aborts launch when GH_TOKEN is missing.
• ignore — wipe any forwarded hosts.yml and export nothing.

Resolution order, most-specific first:

• [roles.<role>.github].auth_forward in workspaces/<ws>.toml
• [github].auth_forward in workspaces/<ws>.toml
• [github].auth_forward (global default)

Operator-only — role manifests cannot set or override [github], same rule as [claude] / [codex] / [kimi] / [opencode] / [grok]. Optional GHE-targeted env vars GH_HOST and GH_ENTERPRISE_TOKEN may also be set in the […github.env] block; they are forwarded to the container as-is.

Telemetry settings

Global telemetry settings live in config.toml under [telemetry]:

[telemetry]
level = "debug"              # "info" (default), "debug", or "trace"
categories = ["docker", "launch"]

level controls host/capsule OTLP verbosity. categories is an optional allowlist for governed debug-category records before OTLP export; omit it to allow every debug category. Environment variables win over config: JACKIN_TELEMETRY_LEVEL overrides level, and JACKIN_TELEMETRY_CATEGORIES overrides categories.

Operator env layers

Four layers contribute env vars to the agent container, merged with later-wins semantics:

# Layer 1 — global
[env]
OPERATOR_ORG = "acme-corp"

# Layer 2 — per role
[roles.agent-smith.env]
API_TOKEN = "op://Personal/api/token"

# Layer 3 — per workspace
[env]
REGISTRY = "${COMPANY_REGISTRY_URL}"

# Layer 4 — per (workspace, role)
[roles.agent-smith.env]
API_TOKEN = "op://Work/shared-smith/token"

Layer 3 and 4 env blocks are stored in ~/.config/jackin/workspaces/big-monorepo.toml.

Values can be:

• op://VAULT/ITEM/FIELD — resolved via the 1Password CLI (op read)
• $NAME or ${NAME} — read from the host env
• Anything else — literal

See Environment Variables for the full guide.

Workspaces

workdir = "/home/user/Projects/my-app"
allowed_roles = ["agent-smith", "the-architect"]
default_role = "agent-smith"
default_agent = "amp"
last_role = "the-architect"

[[mounts]]
src = "/home/user/Projects/my-app"
dst = "/home/user/Projects/my-app"
readonly = false
isolation = "worktree"

[[mounts]]
src = "/home/user/cache"
dst = "/cache"
readonly = true

[keep_awake]
enabled = true

[runtime]
backend = "docker"

git_pull_on_entry = true

This example is the contents of ~/.config/jackin/workspaces/my-app.toml; there is no [workspaces.my-app] header inside the file.

When you use jackin workspace create, workdir is only the container start path. Add an explicit --mount for every directory the container should see.

Global mounts

[docker.mounts]
gradle-cache = { src = "/home/user/.gradle/caches", dst = "/home/agent/.gradle/caches", readonly = true }

[docker.mounts."chainargos/*"]
secrets = { src = "/home/user/.chainargos/secrets", dst = "/secrets", readonly = true }

Global mounts are stored by name. Unscoped mounts live directly under [docker.mounts]. Scoped mounts live under a scope key such as [docker.mounts."chainargos/*"].

Git co-author trailer

When coauthor_trailer is true, jackin❯ installs a shared prepare-commit-msg hook inside the role container the first time a session needs it. The hook is a symlink to jackin-capsule, so trailer normalization runs through the same Rust binary that owns deterministic runtime setup. It reads which agent is running and appends that agent's Co-authored-by trailer whenever Git asks the hook to prepare a commit message, including amended, reused, squash, and merge messages. Existing agent trailers are preserved, so a commit touched by multiple agents keeps each involved agent in the final trailer block.

When dco is true, the same hook also appends a Signed-off-by DCO trailer read from git config user.name and git config user.email inside the container. Matching existing trailer lines are normalized into Git's final trailer block before commit creation. The two fields are independent: enable either or both.

[git]
coauthor_trailer = true  # enable Co-authored-by agent trailer
dco = true               # enable Signed-off-by DCO trailer

The [git] table is omitted from config.toml when all fields are at their defaults (the table is not written unless the operator sets it). See Schema Versions for the field-level reference.

Persisted state

Each running role stores state at ~/.jackin/data/<container-name>/:

Host→container auth handoff lives under a single tree (/jackin/) the operator can audit at a glance. The agent home directories are bind-mounted from jackin-managed per-instance state, not from the operator's host home. jackin-capsule runtime-setup seeds image-baked defaults into that durable home on first launch, then copies the current auth handoff files from /jackin/ into the durable home before starting the agent. This keeps conversation history and runtime-local plugins recoverable when Docker containers disappear while still letting the current auth mode override stale forwarded credentials.

For roles that list multiple supported agents in their manifest, jackin❯ provisions claude/, codex/, amp/, kimi-code/, opencode/, and grok/ auth handoff directories and their corresponding home/.claude/, home/.codex/, home/.local/share/amp/, home/.kimi-code/, home/.local/share/opencode/, and home/.grok/ durable home directories for every agent the role supports — not just the agent selected for the initial launch. This means starting a second agent via jackin hardline --new does not require re-authentication: the credentials and durable home were already placed in the container when it first launched.

claude/account.json is rebuilt as {} (empty object) by every non-sync auth mode so it is always present on disk; the bind mount is the gate for whether the file flows into the container, not the file's existence. claude/credentials.json is wiped on every non-sync mode and never bind-mounted under ignore/api_key/oauth_token.

Delete with jackin purge <role> to start fresh.