Configuration

How kin resolves its settings: the 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.

Four ways to configure

Every knob — the model, provider/wire API, endpoint, sampling, permission mode, and more — can be set explicitly or supplied by a preset:

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"	Use a stable provider identity: direct OpenAI/Anthropic, curated MiniMax/Z.ai, or a custom endpoint. Curated presets also supply the model id.

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

Provider and wire identity follow that same chain independently. For example, --wire-api responses beats KIN_WIRE_API, which beats wire_api in the merged files, which beats the selected preset’s wire, which finally falls back to Chat. A public chat or responses selection implies OpenAI; a bare custom base URL with neither identity axis selected retains the Anthropic Messages heuristic.

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 choice and preferences.
• 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.

The global file has two kin-managed siblings you never need to edit: ~/.kin/credentials.toml (API keys and tokens, created 0600 — written by kin connect and the in-app key prompts) and ~/.kin/grants.toml (sandbox and Git-host approval grants — managed with /grants). They merge into the same view; the split keeps settings.toml short and entirely yours. Run kin settings any time to see the effective configuration, which file or env var supplies each key, and configuration lint (typos, mis-scoped keys).

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, sandbox_network	A repo must not be able to disable or widen OS/network containment or opt strict mode into sandboxed autonomy.
sandbox_grants, sandbox_always_allow	Typed human-owned authority and inert migration data cannot come from a checkout.
git_host_grants	A repo must not be able to trust its own SSH/HTTPS credential route. Kin writes secret-free rows only after Trust host in the Git credential modal; manage them with /grants.
shell_allowlist	A repo must not be able to turn off the read-only-command gate.
ssh_hosts	Deprecated inert compatibility data; it remains global-only so old project data cannot influence migration surfaces.
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.

Set these knobs in the global layer only (file, env, or flag). Secrets you enter through kin land in ~/.kin/credentials.toml automatically (created chmod 600); a secret pasted into a legacy settings.toml still works and moves there on the next settings write. 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

Planning drafts are durable files under the project:

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

The file survives “keep planning,” a rejection, or a mid-plan quit, and the review modal exposes its path. The planning freeze and human review choices are explained in Modes & approvals. Tool argument and revision mechanics belong to the maintainer Reference, not this configuration path. persist_plans is a retired compatibility key and no longer changes behavior.

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/AGENTS.md, src/kin/tui/AGENTS.md, and container/AGENTS.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.

Shell commands and run_code source count as touching too: their raw text is scanned (bounded, best-effort) for workdir paths that exist on disk, so grep, cat, or an inline python3 -c "open('data/…')" over a guided subtree surfaces the same guidance files. Listing or searching a directory (ls, grep, a shell command naming it) surfaces that directory’s own guidance as well as its ancestors’. One seen-set covers every door — a subtree’s guidance never arrives twice just because it was touched first through shell and later through a file tool, and /clear resets it all the same way.

.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 and docs/decisions/0147-guidance-paths-seam.md for the shell/run_code trigger and the dir-inclusive walk.

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
KIN_DETACH	=1 runs interactive launches as persistent sessions — /detach leaves them running; a closed terminal or dropped SSH no longer kills the live turn.	detach

File errors

A malformed settings file degrades to “no settings” with a warning rather than crashing. Set KIN_STRICT_SETTINGS=1 when a managed environment should fail instead. For provider connection examples, use the single canonical journey in Connect a model and first run.

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.