Environment variables

Every environment variable kin reads. Environment variables sit above both settings.toml files in precedence and below CLI flags, so an exported KIN_* is always a one-off override. For the full precedence model, see Configuration.

Variables

The scope column matches the variable's settings.toml equivalent: project-ok keys may live in a project file, global-only keys are honored only from the global file / env / CLI, and env only variables have no settings key. See settings.toml keys for the file side.

Backend and model

Variable	What it does	settings.toml key	Scope
KIN_PROVIDER	Wire: openai or anthropic. With a base URL set and no provider, the vLLM heuristic picks anthropic.	provider	project-ok
KIN_MODEL	Model id. Set to default to follow whatever model your local server (vLLM/Ollama) is currently running — the harness probes /v1/models on session start and reads response.model off each turn so the displayed name always reflects the live server. The alias is sent verbatim on the wire.	model	project-ok
KIN_BASE_URL	OpenAI-compat endpoint URL (a trailing /v1 is trimmed for the Anthropic wire).	base_url	global-only
KIN_PRESET	First-party provider preset id (built-ins: minimax, zai). Bundles wire + URL + default model + auth style.	provider_preset	global-only
KIN_API_KEY	Endpoint auth (OpenAI-compat wire).	api_key	global-only
OPENAI_API_KEY	Endpoint auth, fallback after KIN_API_KEY (OpenAI-compat wire).	api_key	global-only
ANTHROPIC_API_KEY	Endpoint auth (Anthropic wire).	api_key	global-only
KIN_CONTEXT_WINDOW	Token budget for the context meter.	context_window	project-ok
KIN_MAX_TOKENS	Per-response output cap.	max_tokens	project-ok
KIN_TEMPERATURE	Sampling temperature (OpenAI-compat wire only).	temperature	project-ok
KIN_TOP_P	Nucleus sampling top_p (OpenAI-compat wire only).	top_p	project-ok
KIN_TOP_K	top_k via extra_body (OpenAI-compat wire only).	top_k	project-ok
KIN_ENABLE_THINKING	Qwen3-style thinking soft switch (OpenAI-compat wire only).	enable_thinking	project-ok
KIN_REASONING_EFFORT	OpenAI-proper reasoning-effort hint — real OpenAI / OpenRouter / Z.ai OpenAI-compat GLM-5.2+ (NOT for Qwen vLLM, which uses KIN_ENABLE_THINKING). Top-level wire field on chat.completions.create. The resolver is opaque to per-serve vocab; the picker (see Models & providers) translates the cross-wire effort knob.	reasoning_effort	project-ok
KIN_STRICT_TOOLS	Strict tool schemas on the streaming registry path (OpenAI-compat wire only, default off) — each tool spec ships a strict-normalized copy (additionalProperties: false, all-required, optionals as null-unions) + strict: true, so endpoints that honor it (OpenAI-proper; vLLM ≥ 0.24 auto tool choice) grammar-enforce the arguments. See Strict decoding.	strict_tools	project-ok
KIN_EFFORT	Anthropic adaptive-thinking effort (default high).	effort	project-ok
KIN_THINKING_TYPE	Anthropic-wire thinking.type knob (default adaptive) — z.ai / MiniMax / Fable's canonical reasoning control. Common values: adaptive, enabled, disabled (the disabled shape 400s on some serves).	thinking_type	project-ok
KIN_CACHE_TTL	Anthropic system-prompt prefix-cache TTL (1h opts into the 1-hour cache).	cache_ttl	project-ok
KIN_CACHE_MIN_PREFIX_TOKENS	Minimum prefix length before the Anthropic prefix cache engages.	—	env only
KIN_IMAGE_DETAIL	OpenAI vision tier for tool-returned images (low / high / auto).	image_detail	project-ok
KIN_STREAM_STALL_TIMEOUT	Seconds of silence (no stream event) before a model turn is aborted as stalled, on both the Anthropic and OpenAI-compat wires (default 120). Guards against a compat endpoint that keeps a connection open with keep-alive bytes after silently dropping the generation — observed on MiniMax's /anthropic endpoint, which otherwise leaves the UI stuck on "thinking" forever.	—	env only

Permissions and sandbox

Variable	What it does	settings.toml key	Scope
KIN_MODE	Permission mode at launch (auto / strict; the legacy default / accept-edits / plan still resolve via the alias map).	mode	global-only
KIN_SANDBOX	OS sandbox backend for auto-mode shell (auto / seatbelt / bwrap / off / container). container trusts an external boundary so auto-mode shell runs unconfined instead of asking (see the auto-mode guide).	sandbox	global-only
KIN_SANDBOX_STRICT	Opt strict mode's shell into the OS sandbox.	sandbox_strict	global-only
KIN_SANDBOX_DEFAULT	Legacy (pre-two-mode) name, still honored as a fallback for KIN_SANDBOX_STRICT.	sandbox_default	global-only
KIN_SHELL_ALLOWLIST	Set to a falsy value to disable the read-only shell allowlist (every command then asks).	shell_allowlist	global-only

Fleet safety

Variable	What it does	settings.toml key	Scope
KIN_TOKEN_BUDGET	Per-run cumulative token budget (prompt + completion, summed across every model round — subagent rounds included). A budget hit stops the run cleanly at the next model-round boundary (done reason token_budget; headless exit 1). 0 / unset = off. Human-only — not model-writable. See Fleet safety.	token_budget	project-ok
KIN_MAX_TURNS	Per-turn model-round cap: the maximum model↔tool round-trips one user turn may take before it ends with done reason turn_cap. 0 / unset = unlimited (the default) — the doom-loop guard (3× identical call+result) is the real no-progress backstop, so an unbounded cap is safe for long-running agentic turns. Human-only — not model-writable.	max_turns	project-ok
KIN_REQUEST_PRIORITY	vLLM priority-scheduling passthrough (extra_body["priority"], lower = earlier; OpenAI-compat wire only — the Anthropic /v1/messages protocol has no priority field). Serve-gated: requires --scheduling-policy priority on the server; vLLM errors on a non-zero priority otherwise, so the default is absent, not 0. See Models & providers.	request_priority	project-ok

Planning

Variable	What it does	settings.toml key	Scope
KIN_PERSIST_PLANS	Retired, no-op — plans are now saved to <workdir>/.kin/plans/ unconditionally on every write_plan call. Kept only so an existing settings.toml/env doesn't error.	persist_plans	project-ok

Sessions and persistence

Variable	What it does	settings.toml key	Scope
KIN_SESSION_DIR	Directory for session journals (the usual override; takes precedence over the settings key).	session_dir	global-only
KIN_NO_SAVE	Run ephemerally — write no journal.	no_save	global-only
KIN_HOME	Relocate the ~/.kin base where settings.toml (and the default projects/ journal root) live.	—	env only
KIN_STATUS_FILE	Path to a best-effort JSON state sidecar a wrapper writes/reads. kin writes running / waiting / idle there atomically; unset (a plain kin run) = no sidecar. Advisory only — never authoritative for liveness. (The Outpost's ttyd→tmux→kin pipeline was the one consumer before the middle-way plan's Step 3 ttyd cut, 2026-07-06, DR 0033; no current wrapper sets this env var.)	—	env only

Context and compaction

Variable	What it does	settings.toml key	Scope
KIN_ENV_CONTEXT	Set to 0 to omit the Environment + git-state blocks from the system prompt.	env_context	project-ok
KIN_COMPACT_THRESHOLD	Auto-compact history once usage crosses this fraction of the window (auto-compaction is off unless set).	compact_threshold	project-ok
KIN_COMPACT_KEEP_TURNS	Minimum recent turns to preserve when compacting (default 4).	compact_keep_turns	project-ok

Skills, tools, and web

Variable	What it does	settings.toml key	Scope
KIN_STRICT_SKILLS	Set to 1 to raise on malformed skill / agent frontmatter instead of graceful-degrading.	strict_skills	project-ok
KIN_SEARCH_ENABLED	Set to 1 to register the search_workspace tool (ranked full-text search over workspace content, stdlib SQLite FTS5). Off by default.	search_enabled	project-ok
KIN_RUN_CODE	Set to 0 to unregister the run_code / run_code_reset interpreter tools (the stateful per-session Python kernel). On by default — they ride the full shell permission gate.	run_code_enabled	project-ok
KIN_DIAGNOSTICS	Set to 0 to disable the diagnostics-after-edit lint pass appended to write_file/edit_file results (ruff check, v1). On by default; shutil.which-gated (no-op if the linter isn't installed) and never blocks or fails the write.	diagnostics_after_edit	project-ok
KIN_DIAGNOSTICS_TY	Set to 1 to also run an opt-in ty typecheck pass inside diagnostics-after-edit. Off by default (ty is slow and typed-project-specific).	diagnostics_ty	project-ok
KIN_SNAPSHOTS	Set to 0 to disable the file snapshot-before-write safety net (/rewind files/both's source). On by default; a no-op outside a git workspace.	snapshots	project-ok
KIN_PASTE_MENTIONS	Set to 0 to make the Composer insert Finder drag-drops / terminal pastes of absolute file paths verbatim instead of converting them to @-mentions. On by default.	paste_file_mentions	project-ok
KIN_SPANS	Set to 1 to write OTel-GenAI-shaped JSONL spans (invoke_agent / chat / execute_tool; metadata only — no prompt/tool text) next to each session journal (<session_id>.spans.jsonl). Off by default.	spans_enabled	project-ok
KIN_PRICING	Set to 1 to display a running USD cost total (/tokens, StatusBar). Sourced from a stdlib pricing table keyed by (provider, model id); an unpriced serve shows nothing. Off by default. See Cost display.	pricing_enabled	project-ok
KIN_BROWSER	Set to 0 to unregister the browser tool (the text-only headless browser). On by default — the tool also needs the optional browser extra installed before it registers at all.	browser_enabled	project-ok
KIN_BROWSER_PRIVATE	Set to 1 to let the browser tool navigate to private/loopback addresses (local dev servers) — the SSRF guard refuses them by default.	browser_allow_private	global-only
KIN_MEMORY	Set to 0 to unregister the memory tool and disable the memory index/recall injections. On by default.	memory_enabled	project-ok
KIN_MEMORY_REFLECT	Set to 0 to skip the end-of-run memory reflection pass (a bounded extra turn over the live memory tool, fired automatically on a clean kin -p stop and at TUI quit). On by default; a run that succeeded is never recorded as error because of it.	memory_reflect	project-ok
KIN_MEMORY_DIR	Relocate the memory root (e.g. for a workspace-local store). Default ~/.kin/memory.	memory_dir	global-only
KIN_SSH_HOSTS	Comma-separated allowlist of hosts (or ~/.ssh/config aliases) the opt-in ssh tool may reach. Empty / unset = the tool isn't registered.	ssh_hosts	global-only
KIN_OUTPOST_URL	Your Outpost's origin (e.g. https://outpost.kinra.ai) — the outpost/outpost-send tools' target. Both tools register only when this AND KIN_OUTPOST_TOKEN resolve.	outpost_url	global-only
KIN_OUTPOST_TOKEN	The bearer token (svc_<id>.<secret>) authenticating the outpost/outpost-send tools against your Outpost's v1 API.	outpost_token	global-only
BRAVE_API_KEY	Brave Search key; enables the web_search / web_context tools.	brave_api_key	global-only
KIN_BRAVE_API_KEY	Alternate name for the Brave key, read after BRAVE_API_KEY.	brave_api_key	global-only
KIN_MCP_TRUST	Path to the persistent MCP server trust store.	—	env only
KIN_MCP_AUTH	Directory for per-server MCP OAuth token state (default ~/.kin/mcp_auth/; files are 0600).	—	env only

Background subagents

Variable	What it does	settings.toml key	Scope
KIN_BG_REMINDERS	Set to a falsy value (0 / false / no / off) to skip the model-facing <system-reminder> for completed bg subagents. The agent panel still shows completions.	bg_completion_reminders	project-ok

Scheduled jobs & the v1 service registry (Outpost operator)

These are read by the Outpost dashboard / scheduler (container/dashboard/), not the harness proper. Operator/deployment-scoped, never written to settings.toml.

Variable	What it does	settings.toml key	Scope
KIN_MASTER_KEY	The v1 service-registry Key Encryption Key (KEK) — a Fernet key that wraps every service's bearer token + webhook signing secret at rest in services.db (container/dashboard/keystore.py, services_db.py; PROTOCOL.md §2.1). Resolution order: this env var (the deployment-time secret-manager path) → the 0600 key file at <kin_home>/keystore/service_kek.bin (auto-generated on first dashboard startup / first kin service create, refused if group/other-readable). Ignored (with a logged error) if set to something that isn't a valid Fernet key. Also the NEW key during a kin service rekey rotation. KEK loss is recoverable-by-re-registration only — every service must re-register.	—	env only
KIN_OLD_MASTER_KEY	The PREVIOUS KEK during a kin service rekey rotation (container/dashboard/services_db.py::rekey, src/kin/harness/cli/service.py). rekey needs BOTH env vars — KIN_OLD_MASTER_KEY (decrypt with the current key) + KIN_MASTER_KEY (re-encrypt with the new key) — and rotates every service secret in one transaction. Generate a new key with python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())".	—	env only
KIN_GPU_PRIORITY	Operator opt-in for cross-run GPU fairness on a shared vLLM (container/dashboard/scheduler.py). When set, the Outpost scheduler flips each scheduled job onto the OpenAI-compat wire and stamps a non-zero KIN_REQUEST_PRIORITY on it, so a vLLM serve running --scheduling-policy priority preempts batch work in favor of the interactive TUI session (which stays on the Anthropic wire with no priority field = priority 0 = wins preemption). Default unset = status quo (scheduled jobs ride the Anthropic wire, no priority field). Requires the --scheduling-policy priority serve flag (vLLM 400s on a non-zero priority otherwise). See Scheduled jobs.	—	env only
KIN_JOB_ID / KIN_JOB_NAME	Set by the Outpost scheduler on a scheduled job's kin -p subprocess env (container/dashboard/scheduler.py), never by an operator directly. Read by the harness's end-of-run memory reflection to tag that job's memory writes, so a recurring job updates ONE memory in place instead of accumulating near-duplicates across runs.	—	env only

Meta and UI

Variable	What it does	settings.toml key	Scope
KIN_STRICT_SETTINGS	Set to 1 to raise on a malformed settings.toml instead of degrading to no settings.	—	env only
KIN_ASCII	Force plain-ASCII rendering — the welcome banner (no box-drawing) and the ASCII-safe line spinner style.	—	env only
KIN_SPINNER	The busy-spinner style name (bloom · braille · arc · toggle · line — see Identity). Unknown names fall back to the default; pick interactively with /spinner.	spinner	project-ok
KIN_NOTIFY	Set to 0 to disable the terminal bell / OSC 9 walk-away notification — a completion bell on a turn that ran 15s+ and on every needs-input prompt (TUI), or on process completion when stderr is a real terminal (kin -p). On by default.	notify	project-ok

Host environment kin also reads

Beyond its own knobs, kin reads a few standard host variables: SHELL, LANG, and LC_ALL feed the environment block in the system prompt; TMPDIR scopes the OS sandbox's writable temp path; and XDG_CONFIG_HOME locates user-level AGENTS.md guidance. These are not kin configuration — they are the ambient environment it observes.

For the meaning of provider, base_url, and the sampling knobs, see Models & providers. For the global-only safety boundary, see settings.toml keys.