---
title: Configuration File
description: "The config.toml schema and storage locations"
---
import { Aside } from '@astrojs/starlight/components'

<Aside type="note">
This page is an **internals reference** for contributors and operators
who want to read, audit, or hand-edit jackin's config file directly —
typically while debugging or shipping a fix. Day-to-day operator work
goes through `jackin workspace …`, `jackin config …`, and the
operator console, none of which require touching this file. Start
from the [Operator Guide](/guides/workspaces/) instead if that is
what you're after.
</Aside>

## Storage locations

| Path | Purpose |
|---|---|
| `~/.config/jackin/config.toml` | Global operator configuration (auth defaults, role trust/source, global mounts, global env) |
| `~/.config/jackin/workspaces/<name>.toml` | One saved workspace per file. The workspace name is the filename stem. |
| `~/.jackin/roles/` | Cached role repository checkouts |
| `~/.jackin/data/<container-name>/` | Persisted agent state (Claude history, settings, GitHub CLI config, plugins) |

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

| Variable | Default | Overrides |
|---|---|---|
| `JACKIN_CONFIG_DIR` | `~/.config/jackin` | Config root — `config.toml`, `workspaces/` |
| `JACKIN_HOME_DIR` | `~/.jackin` | Jackin home root — `data/`, `roles/`, `cache/` |
| `JACKIN_CONSTRUCT_IMAGE` | `projectjackin/construct:trixie` | Override the construct base image used at derived-build time. Role Dockerfiles always reference the canonical name; this substitutes it during `docker build`. Set to `jackin-local/construct:trixie` after `just construct-build-local` to test against a local construct build. See [The Construct Image](/developing/construct-image/) for the full workflow. |

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](https://www.chezmoi.io/) 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 = "v1alpha4"` stamp, so a dotfile-managed setup that is partially old (some workspaces stamped, some not) migrates per-file on first load. See [Schema Versions](/reference/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 = "v1alpha5"` today. Older config files with no `version` are treated as legacy and migrated automatically on startup before parsing. See [Schema Versions](/reference/schema-versions/) for the full version history and migration matrix.

### Agent auth-forward settings

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

```toml
version = "v1alpha5"

# Layer 1 — global default (per agent)
[claude]
auth_forward = "sync"  # "sync" (default), "api_key", "oauth_token", or "ignore"

[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"

# 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"

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

[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"
```

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

| Field | Description | Default |
|---|---|---|
| `auth_forward` | How the host's agent credentials (or env-supplied keys/tokens) are made available to agent containers. See [Authentication Forwarding](/guides/authentication). | `sync` |

Accepted values: `sync` \| `api_key` \| `oauth_token` \| `ignore`.
`oauth_token` is **Claude only** — setting it under any `[codex]`,
`[amp]`, `[kimi]`, or `[opencode]` 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`
- `[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`
- `[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)

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`, and `OPENCODE_API_KEY`.

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

```toml
# 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]`. 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.

### Operator env layers

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

```toml
# 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

<Aside type="caution" title="Reserved names cannot be overridden">
A small set of names is owned by the jackin' runtime and set internally on every launch. Declaring them at any of the four layers above is rejected at config load. See [Reserved names](/guides/environment-variables/#reserved-names) for the canonical list.
</Aside>

See [Environment Variables](/guides/environment-variables/) for the full guide.

### Workspaces

```toml
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

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.

| Field | Description |
|---|---|
| `workdir` | Container working directory |
| `mounts` | Array of mount specifications |
| `mounts[].src` | Host path |
| `mounts[].dst` | Container path |
| `mounts[].readonly` | Read-only flag |
| `mounts[].isolation` | Per-mount isolation mode: `shared` (default), `worktree`, or `clone`. Omitting the field deserializes to `shared`, but every save writes the field explicitly so old configs migrate to the new shape on first save. Global mounts (under `[docker.mounts]`) reject this field at parse time. See [Per-mount isolation](/guides/workspaces/#per-mount-isolation). |
| `allowed_roles` | List of allowed role selectors |
| `default_role` | Default role selector |
| `default_agent` | Optional workspace default agent (`"claude"`, `"codex"`, `"amp"`, `"kimi"`, or `"opencode"`). Omit to default to Claude. |
| `last_role` | Most recently used role selector for this workspace |
| `keep_awake.enabled` | macOS-only: keep the host awake while any agent in this workspace is running (see [Keeping the host awake](/guides/workspaces/#keeping-the-host-awake)). On Linux/Windows the flag is silently accepted but has no effect — useful when sharing a `config.toml` across machines, but the host will still sleep. |
| `git_pull_on_entry` | Run `git pull` on every mounted git repository from the host before the agent container starts. Failures are non-fatal — the launch continues even when offline or the working tree is dirty. Omitted from TOML when `false` (the default). See [Git pull on entry](/guides/workspaces/#git-pull-on-entry). |

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

```toml
[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 `prepare-commit-msg` hook inside every role container on launch. The hook reads which agent is running and appends the correct `Co-authored-by` trailer to every new commit message automatically. Amend operations are skipped so the trailer is not added twice.

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. The two fields are independent: enable either or both.

```toml
[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](/reference/schema-versions/#v1alpha5) for the field-level reference.

## Persisted state

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

| File/Directory | Purpose |
|---|---|
| `claude/account.json` | Claude Code account metadata (mounted at `/jackin/claude/account.json` in the container; only forwarded under `auth_forward = "sync"`) |
| `claude/credentials.json` | Claude Code OAuth credentials (mounted at `/jackin/claude/credentials.json`; only forwarded under `auth_forward = "sync"`) |
| `codex/auth.json` | Synced copy of host `~/.codex/auth.json` under `auth_forward = "sync"`, `0600` perms (mounted at `/jackin/codex/auth.json`; absent when host has no auth.json) |
| `amp/secrets.json` | Synced copy of host `~/.local/share/amp/secrets.json` under `auth_forward = "sync"`, `0600` perms (mounted at `/jackin/amp/secrets.json`; absent when host has no secrets.json). `secrets.json` is the XDG_DATA file the Amp CLI writes the `apiKey@https://ampcode.com/` token into; the XDG_CONFIG path `~/.config/amp/settings.json` is preferences only and is intentionally not forwarded |
| `kimi/config.toml` | Synced copy of host `~/.kimi/config.toml` under `auth_forward = "sync"`, `0600` perms (mounted under `/jackin/kimi/` and copied into `/home/agent/.kimi/` before Kimi starts). Kimi stores OAuth tokens separately, but its login flow writes the OAuth-backed provider/model/service references into this config file, so a fresh default config is not enough to use the forwarded token. |
| `kimi/credentials/` | Synced copy of host `~/.kimi/credentials/` OAuth token files under `auth_forward = "sync"`, `0600` perms |
| `kimi/device_id` | Synced copy of host `~/.kimi/device_id` under `auth_forward = "sync"`, `0600` perms; Kimi includes this device id in OAuth/device headers |
| `opencode/auth.json` | Synced copy of host `~/.local/share/opencode/auth.json` under `auth_forward = "sync"`, `0600` perms (mounted at `/jackin/opencode/auth.json`; absent when host has no auth.json). OpenCode stores provider credentials in this file — for example, a Z.AI Coding Plan API key |
| `home/.claude/` and `home/.claude.json` | Durable Claude Code home state, including conversation history, runtime-local plugins, account metadata, and settings written during the session |
| `home/.codex/` | Durable Codex home state, including conversation history, runtime-local config, and login state created inside the session |
| `home/.local/share/amp/` | Durable Amp data state created inside the session |
| `home/.kimi/` | Durable Kimi home state, including runtime-local config and login state created inside the session |
| `home/.local/share/opencode/` | Durable OpenCode data state (auth credentials, model preferences) created inside the session |
| `state/` | jackin runtime state mounted at `/jackin/state`, including the `setup_once` marker |
| `.config/gh/` | GitHub CLI authentication and settings (agent-neutral) |

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. The runtime entrypoint 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/`, and `opencode/` auth handoff directories and their corresponding `home/.claude/`, `home/.codex/`, `home/.local/share/amp/`, `home/.kimi/`, and `home/.local/share/opencode/` 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.
