# 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. 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](/docs/kin/reference/cli/), the env vars in [Environment variables](/docs/kin/reference/environment-variables/), and the file keys in [settings.toml keys](/docs/kin/reference/settings-toml/). > **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](/docs/kin/guide/slash-commands/#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: ```text 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](/docs/kin/guide/auto-mode-and-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** — `/.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`](/docs/kin/reference/cli/#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](https://github.com/kinra-ai/kin/blob/dev/REFERENCE.md). ## 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: ```text /.kin/plans/-NN-.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](/docs/kin/guide/modes-and-permissions/#planning). Tool argument and revision mechanics belong to the maintainer [Reference](https://github.com/kinra-ai/kin/blob/dev/REFERENCE.md), 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`](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0073-nested-agents-md.md) for the design and [`docs/decisions/0147-guidance-paths-seam.md`](https://github.com/kinra-ai/kin/blob/dev/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](/docs/kin/reference/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](/docs/kin/guide/browser/) tool (global-only key, opt-in). | [`browser_allow_private`](/docs/kin/reference/settings-toml/) | | `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`](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0004-strategy-missing-lanes.md) § GPU governance). Applies to scheduled-job subprocesses too. | [`token_budget`](/docs/kin/reference/settings-toml/) | | `KIN_MAX_TURNS` | Per-turn model-round cap (max model↔tool round-trips in one user turn; `0` = unlimited, the default). | [`max_turns`](/docs/kin/reference/settings-toml/) | | `KIN_CACHE_MIN_PREFIX_TOKENS` | Minimum prefix length before the Anthropic prefix cache engages. Tunable for cache-friendliness vs cache-busting. | [Environment variables](/docs/kin/reference/environment-variables/) | | `KIN_HOME` | Relocates the whole `~/.kin` base (sessions, memory, plans, settings). | [Environment variables](/docs/kin/reference/environment-variables/) | | `KIN_DETACH` | `=1` runs interactive launches as [persistent sessions](/docs/kin/guide/sessions/#background-sessions-detach-reattach) — `/detach` leaves them running; a closed terminal or dropped SSH no longer kills the live turn. | [`detach`](/docs/kin/reference/settings-toml/) | ## 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](/docs/kin/getting-started/first-run/#alternative-connection-methods). For the complete list of keys with their types, defaults, and scope, see [settings.toml keys](/docs/kin/reference/settings-toml/). The matching env vars are in [Environment variables](/docs/kin/reference/environment-variables/), and the launch flags in [CLI flags](/docs/kin/reference/cli/).