Environment variables

Environment variables override settings files and yield to CLI flags. An exported value affects each process that inherits it; prefix a command to limit the override to that launch. See Configuration for precedence.

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) or alias-aware gateway 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 by Kin; an endpoint such as the Kinra public gateway may resolve it to its configured primary.	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	Advertised context window used to derive prompt limits and the below-composer current / hard-limit display.	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); the Z.ai preset sends its GLM-5.3 max / high / low value as output_config.effort.	effort	project-ok
KIN_THINKING_TYPE	Anthropic-wire thinking.type knob (default adaptive) — z.ai / MiniMax / Fable use it as a thinking toggle. Common values: adaptive, enabled, disabled; always-reasoning GLM-5.3 maps a disabled toggle to lightweight reasoning.	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 600). Guards against a compat endpoint that keeps a connection open with keep-alive bytes after silently dropping the generation.	—	env only

Permissions and workspace trust

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_SHELL_ALLOWLIST	Set to a falsy value to disable the read-only shell allowlist (every command then asks).	shell_allowlist	global-only
KIN_TRUSTED_BOUNDARY	Set to container only when an operator-provisioned container, VM, appliance, or dedicated account already owns the whole-process filesystem/network/credential boundary. Kin skips the local trust prompt and runs normally inside that boundary.	—	env only

Fleet safety

Variable	What it does	settings.toml key	Scope
KIN_TOKEN_BUDGET	Per-run cumulative token budget (non-cached prompt + completion, summed across root, subagent, vision, and compaction calls). The crossing round finishes; only the root receives one final tools-off wrap-up round before done reason token_budget (headless exit 1). Children receive no grace. 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 the current hosted contract does not expose this control, 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_HOME	Relocate the ~/.kin base where settings.toml (and the default projects/ journal root) live.	—	env only

Herdr injects HERDR_ENV, HERDR_PANE_ID, and HERDR_BIN_PATH into panes. They are not Kin settings: the interactive entry validates them only to enable best-effort lifecycle reporting. Headless Kin never installs the reporter, and an incomplete, unsafe, or forged set is ignored.

Context and compaction

Variable	What it does	settings.toml key	Scope
KIN_ENV_CONTEXT	Set to 0 to omit the stable Environment block and per-root-turn date/Git reminder.	env_context	project-ok
KIN_COMPACT_THRESHOLD	Auto-compact once prompt usage crosses this fraction of the window (default 0.45; 0 disables); 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
KIN_COMPACT_KEEP_FRACTION	Ceiling on the retained tail’s estimated tokens as a fraction of the window (default 0.16; 0 disables). Outranks KIN_COMPACT_KEEP_TURNS down to one kept turn; exact-count pressure may tighten, never loosen, the ceiling for the observed token density.	compact_keep_fraction	project-ok
KIN_PRUNE_THRESHOLD_CHARS	Elide a completed tool result longer than this before paying for a summarization call (default 8192); 0 disables pruning.	prune_threshold_chars	project-ok
KIN_PRUNE_HEAD_CHARS	Leading characters a pruned tool result keeps (default 4096).	prune_head_chars	project-ok
KIN_PRUNE_TAIL_CHARS	Trailing characters a pruned tool result keeps (default 1024).	prune_tail_chars	project-ok
KIN_SPILL_MAX_BYTES	Per-file cap for the spill store that keeps truncated tool output retrievable via read_spill (default 8388608); 0 disables it, and every no-save route disables it regardless.	spill_max_bytes	project-ok

Skills, tools, and web

Variable	What it does	settings.toml key	Scope
KIN_STRICT_SKILLS	Historical name retained for compatibility: set to 1 to raise on malformed agent-profile frontmatter instead of skipping the profile. Skills are always validated strictly and do not consult this variable.	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_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
BRAVE_API_KEY	Explicit local Brave Search override; enables direct web_search / web_context and takes precedence over hosted routing.	brave_api_key	global-only
KIN_BRAVE_API_KEY	Alternate name for the local Brave override, 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 (default 600). Clamped to 30–3600; never cancels or restarts the child.	agent_stall_timeout	project-ok

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	Use an ASCII welcome frame and divider, omit the emblem, and select the ASCII-safe line spinner. Supplied model names, paths, and trust text remain literal.	—	env only
KIN_MARK	Set to 0 to hide the welcome emblem. Shown by default when there is room; KIN_ASCII takes precedence over KIN_MARK=1.	—	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 locates temporary files; 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.