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	Provider family: openai or anthropic. With a base URL and neither identity axis set, the vLLM heuristic picks Anthropic. Explicit openai without KIN_WIRE_API means Chat.	provider	project-ok
KIN_WIRE_API	OpenAI wire: chat or responses. Either implies OpenAI and bypasses the bare-base-URL Anthropic heuristic. Responses is opt-in; Chat is the default. messages is internal and rejected here.	wire_api	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 for the default backend (a trailing /v1 is trimmed for the Anthropic wire). A selected provider preset owns its endpoint instead; an explicit caller base_url can still override the preset.	base_url	global-only
KIN_PRESET	Provider preset id (built-ins: direct openai / anthropic, plus curated minimax, zai). Bundles wire + endpoint/auth identity; curated presets also supply a default model.	provider_preset	global-only
KIN_API_KEY	Generic endpoint auth fallback. For direct vendor presets it follows that vendor’s conventional variable.	api_key	global-only
OPENAI_API_KEY	Direct OpenAI auth (then KIN_API_KEY); never used by the direct Anthropic preset. Compatibility/custom presets retain the broad legacy fallback chain.	api_key	global-only
ANTHROPIC_API_KEY	Direct Anthropic auth (then KIN_API_KEY); never used by the direct OpenAI preset. Compatibility/custom presets retain the broad legacy fallback chain.	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	Chat-template thinking soft switch for Qwen-style OpenAI-compatible serves and an Anthropic custom provider with reasoning_profile="poolside".	enable_thinking	project-ok
KIN_REASONING_EFFORT	OpenAI reasoning-effort hint — top-level reasoning_effort on Chat, or reasoning.effort on Responses. Qwen-style vLLM serves may instead use KIN_ENABLE_THINKING. The resolver is opaque to each serve’s vocabulary; 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, across Messages, Chat, and Responses (default 120). Guards against a compat endpoint that keeps a connection open with keep-alive bytes after silently dropping the generation.	—	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_NETWORK	Set to 0 to isolate networking inside Seatbelt/bubblewrap; default is network available with workspace/secret containment intact.	sandbox_network	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	Legacy vLLM priority-scheduling passthrough (extra_body["priority"], lower = earlier; OpenAI-compat wire only). Serve-gated: requires --scheduling-policy priority; vLLM errors on a non-zero priority otherwise, and current DS4 does not implement the field, 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 session journal or durable prompt history; composer recall remains memory-only for this process.	no_save	global-only
KIN_PROMPT_HISTORY_CAP	Maximum interactive composer submissions retained per project for ↑/↓ and ++ctrl+r++ across restarts (default 100). 0 makes recall memory-only without deleting retained history; negative or malformed values use 100. Stores submitted model prompts, slash commands, and ! command text—not shell output—and never includes headless kin -p prompts. Every no-save route overrides this and disables durable history.	prompt_history_cap	project-ok
KIN_DETACH	Interactive launches run as background sessions by default when tmux ≥ 3.2 is available (DR 0097); set KIN_DETACH=0 to opt out (=1 forces it on). kin --no-detach always wins; headless -p and launches inside your own tmux are never wrapped.	detach	project-ok
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 once prompt usage crosses this fraction of the window; the output reservation may impose an earlier hard limit.	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 0 to unregister the default-on search_workspace tool (ranked lexical full-text search over workspace content, stdlib SQLite FTS5).	search_enabled	project-ok
KIN_SHELF_ENABLED	Set to 0 to disable shelf board hints and the TUI returned-branch watcher.	shelf_enabled	project-ok
KIN_SHELF_WATCH_INTERVAL	Seconds between fixed-refspec shelf branch probes; minimum 30, default 120, read at TUI mount.	shelf_watch_interval	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_RIG	Set to 0 to unregister the Rig tool family. Registration also requires a URL and token.	rig_enabled	project-ok
KIN_RIG_URL	Rig’s semantic API origin.	rig_url	global-only
KIN_RIG_TOKEN	Rig bearer credential. Deployments prefer the file form below.	rig_token	global-only
KIN_RIG_TOKEN_FILE	Read the Rig bearer from a secret file without exporting it to child environments.	—	env only
KIN_BROWSER	Legacy no-op retained so existing settings do not fail validation.	browser_enabled	project-ok
KIN_BROWSER_PRIVATE	Legacy no-op; local Rig development uses task rig:local.	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 terminal clean kin -p stop with no pending human gate 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_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_AGENT_STALL_TIMEOUT	Seconds without model/tool activity before an active, non-paused task agent becomes advisory stale. Clamped to 30–3600; never cancels or restarts the child.	agent_stall_timeout	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	Legacy vLLM-only scheduler switch. On an explicitly qualified vLLM serve with --scheduling-policy priority, flips background children to OpenAI Chat and stamps their resolved KIN_REQUEST_PRIORITY. Keep unset on the current DS4 fleet: DS4 does not implement this request field, and the named Responses profile must remain intact.	—	env only
KIN_GPU_PRESSURE_URL	Optional URL of a compatible vLLM Prometheus endpoint exposing vllm:num_requests_waiting. Only then may the Background limits card enable defer_when_interactive; absent means the control is unavailable. Keep unset on DS4, which exposes no compatible queue metric. A configured endpoint fails open if its scrape becomes unreachable.	—	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_THEME	TUI theme name. kin is the transparent terminal-ground default; kin-graphite is the opaque Graphite+ fallback. A higher-precedence env value shadows choices saved by /theme.	theme	project-ok
KIN_SPINNER	The busy-spinner style name (rain · 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.