Configuration¶

How kin resolves its settings: the three places you can set a knob, the order they win in, and why some keys are global-only. Read this once and the rest of the configuration just works.

Three ways to configure¶

Every knob — the model, the endpoint, sampling, the permission mode, and more — can be set three ways:

Way	Looks like	Best for
A CLI flag	`kin --model gpt-4o-mini`	A one-off override at launch.
A *`KIN_` env var**	`KIN_MODEL=gpt-4o-mini kin`	Per-shell overrides; CI; secrets from your environment.
A `settings.toml` key	`model = "gpt-4o-mini"`	Your persistent baseline — set it once, every new session reads it.
A provider preset	`KIN_PRESET=minimax uv run kin` or `provider_preset = "minimax"`	Skip the URL + model id + auth header for curated providers (MiniMax, Z.ai).

The flags are listed in CLI flags, the env vars in Environment variables, and the file keys in settings.toml keys.

Tip

You don't have to hand-edit settings.toml. /edit-settings [instruction] lets kin draft the changes and shows a diff to approve (it works in JSON and refuses to draft any hand-edit-only key — containment, egress, secrets, or presets) — see Editing config artifacts. Settings changes apply to new sessions.

Precedence¶

When the same knob is set in more than one place, the more specific source wins. The exact order, highest first:

CLI flag  >  env var (KIN_*)  >  project .kin/settings.toml  >  global ~/.kin/settings.toml  >  default

Because flags and env vars sit above the files, an exported KIN_* or a --flag is always a one-off override — the file is just the persistent baseline underneath. Nothing you already do with env vars regresses when you add a settings.toml.

Default permission mode

With nothing set, kin launches in auto mode (safe autonomy — see Auto mode & the OS sandbox). Set mode = "strict" in your global file to default to the ask-first posture instead. mode is global-only, so a cloned repo can't change it.

Global vs project files¶

There are two file layers, and the project layer overlays the global one:

Global — ~/.kin/settings.toml. Your personal defaults across every project. The right home for your endpoint and key.
Project — <workdir>/.kin/settings.toml, inside the directory you launch kin in. Per-repo overrides (a model or context window suited to that project).

kin loads the global file, then merges the project file on top — so a project key overrides the same global key, and anything the project file omits falls through to your global default.

Global-only (sensitive) keys¶

A handful of keys are honored only from the global file (or env / a flag); if they appear in a project .kin/settings.toml they are stripped and a warning is printed. The reason is concrete: you clone an untrusted repo and launch kin in it. Its project file must not be able to repoint your wire and leak your key, silently launch you into autonomous mode, or weaken the OS containment and shell gate.

Key	Why it's global-only
`base_url`, `api_key`	A cloned repo could repoint your wire and exfiltrate your key.
`provider_preset`, `providers`	A cloned repo's project file could route your global `api_key` through a third-party endpoint silently.
`mode`	A repo must not be able to set your launch mode — force `auto`, or pin you off your chosen default.
`sandbox`, `sandbox_strict`, `sandbox_default`	A repo must not be able to disable OS containment or opt `strict` mode into sandboxed autonomy.
`shell_allowlist`	A repo must not be able to turn off the read-only-command gate.
`ssh_hosts`	A repo must not be able to add a deploy target for the `ssh` tool, which runs outside the OS sandbox.
`session_dir`, `no_save`	Where your sessions live and whether they're saved are yours, not the repo's.
`brave_api_key`	A secret search key — same exfil concern as `api_key`.

Put secrets and these knobs in ~/.kin/settings.toml only. It lives in your home directory and isn't committed; treat it like ~/.aws/credentials and chmod 600 it. The full rationale and the enforcement guarantees are in REFERENCE.md § Settings & config layering.

New sessions vs resume¶

The file layers feed new sessions only. When you resume a session (--resume, --continue, or /resume), kin reproduces the endpoint and model recorded in that session's saved journal — it never re-reads a live settings.toml. Otherwise a global temperature you changed last week could silently re-sample a conversation you thought was frozen. To retarget a resumed session you pass an explicit flag or env var, which still wins by precedence.

Visible plans¶

When the planning flow drafts a plan, write_plan saves it to a durable, re-injectable file:

<workdir>/.kin/plans/<YYYY-MM-DD>-NN-<slug>.md

Every write_plan call — the planner subagent's initial draft, and any later revision by the top-level agent — writes to this file unconditionally; it's the hand-off mechanism between the planner and the top-level agent, so the file survives "keep planning", a rejection, or a mid-plan quit, and the approval modal shows an openable path. The persist_plans setting (KIN_PERSIST_PLANS) predates this and no longer does anything — it's retired, kept only so an existing settings.toml doesn't error.

Consider gitignoring .kin/plans/

kin's .kin/ directory isn't gitignored by default. If you don't want saved plans committed, add .kin/plans/ (or all of .kin/) to your .gitignore.

Per-directory instructions¶

AGENTS.md (or CLAUDE.md as a fallback) in your workdir root is read once at session start, alongside ~/.config/kin/AGENTS.md — see agents_md.discover. In a repo with per-directory guides (this repo's own src/kin/harness/CLAUDE.md, src/kin/tui/CLAUDE.md, and container/CLAUDE.md are the pattern), those subdirectory files aren't part of that root read.

Instead they're surfaced lazily: the moment kin reads or edits a file under a directory that has its own AGENTS.md / CLAUDE.md (same AGENTS.md-over-CLAUDE.md precedence as the root — a CLAUDE.md sibling to an AGENTS.md at the same level is treated as an include shim and skipped), that level's guidance is appended to the tool result the model sees — not the system prompt, and not anything rendered in your transcript. Every directory level between the workdir root and the file's own directory contributes its guidance the first time you touch something in it; a later read or edit in the same subtree does not repeat it. Clearing the conversation (/clear) resets that so guidance can resurface.

.claude/rules/*.md files at each level are picked up the same way, sorted by filename. Each guidance file is capped at 50KiB (the same cap and truncation marker the root-level read uses) so an oversized file can't blow the context window.

This is always on — there's no setting to disable it (v1: it's context, not a behavior toggle). See docs/decisions/0073-nested-agents-md.md for the design.

Commonly-needed environment variables¶

The full list is in Environment variables. The ones a new operator hits first:

Env var	What it does	Pointer
`KIN_BROWSER_PRIVATE`	`=1` admits loopback targets for the browser tool (global-only key, opt-in).	`browser_allow_private`
`KIN_TOKEN_BUDGET`	Per-run cumulative token cap (the per-run leash; not the cross-run GPU-fairness gate — see `docs/decisions/0004-strategy-missing-lanes.md` § GPU governance). Applies to scheduled-job subprocesses too.	`token_budget`
`KIN_MAX_TURNS`	Per-turn model-round cap (max model↔tool round-trips in one user turn; `0` = unlimited, the default).	`max_turns`
`KIN_CACHE_MIN_PREFIX_TOKENS`	Minimum prefix length before the Anthropic prefix cache engages. Tunable for cache-friendliness vs cache-busting.	Environment variables
`KIN_HOME`	Relocates the whole `~/.kin` base (sessions, memory, plans, settings).	Environment variables

Worked example¶

A small global ~/.kin/settings.toml that points kin at a local vLLM server and sets a context budget — enough to launch with a bare kin and no env vars:

# ~/.kin/settings.toml

# --- Backend / model ---
base_url       = "http://localhost:8000/v1"   # base_url set + no provider -> Anthropic wire
model          = "default"                     # auto-pickup: vLLM resolves to the live
                                               # served-model-name; the banner + top bar
                                               # surface the resolved id (see
                                               # guide/models-and-providers.md § "The
                                               # `default` alias pattern"). Pin to a
                                               # specific id (e.g. "Qwen/Qwen3.6-35B-A3B")
                                               # to lock the wire to that model.
context_window = 262144                        # token budget for the context meter
max_tokens     = 32768                         # per-response output cap

# --- Web tools (global-only, like a key) ---
brave_api_key  = "BSA..."                      # enables web_search / web_context

A malformed file degrades to "no settings" with a warning rather than crashing; set KIN_STRICT_SETTINGS=1 to make it raise instead.

For the complete list of keys with their types, defaults, and scope, see settings.toml keys. The matching env vars are in Environment variables, and the launch flags in CLI flags.