Environment variables

Kiki uses environment variables to control a small number of runtime behaviors — relocating the data directory and temporarily switching models without touching the config file.

Kiki-owned runtime controls use the KIKI_* prefix. Provider credential key names such as KIMI_API_KEY and KIMI_BASE_URL remain upstream-facing and are documented separately. Treat the exact names listed on this page as authoritative.

WARNING

Provider API key variables are not read automatically. To use one, set api_key_env = "YOUR_PROVIDER_KEY" in the provider's config.toml table and supply that variable to the Kiki process. See credential priority and example. Stored key values remain in credentials.toml; the environment reference stores only the variable name.

The separate KIKI_MODEL_* family can supply a temporary model and key — see Define a model from environment variables.

Core paths

KIKI_HOME

Overrides the data root directory; the default is ~/.kiki. Once set, the config and credentials files, sessions, logs, OAuth credentials, and all other data land under the new path. The desktop app's OAuth credentials follow KIKI_HOME too: unset, they default to the compatibility home ~/.kimi-code/ (see Data locations).

export KIKI_HOME="/path/to/custom/kiki"

Make sure the directory is writable. Multiple kiki instances sharing the same KIKI_HOME will share config and credential files.

On macOS and Linux, the shared runtime keeps its local endpoint inside this directory, and the resulting path has a length limit that varies by platform. If the path is still too long, Kiki reports a configuration problem naming the actual length, the platform's limit, and the fix: use a shorter KIKI_HOME. Kiki does not move your data for you, and a short symlink does not shorten the real path the limit measures.

After upgrading on macOS or Linux, quit every process still using the same KIKI_HOME before starting the new build — the old and new builds do not share a running runtime. Windows is unaffected: the runtime uses a named pipe there.

For the complete data directory structure, see Data locations.

KIKI_MODEL_* family

Switch models temporarily without modifying config.toml — when KIKI_MODEL_NAME is set, the CLI synthesizes a temporary provider in memory; the change does not persist after restart. See Define a model from environment variables.

Provider credential key names

The names below are the conventional keys for the [providers.<name>.env] sub-table, used as fallback values for api_key / base_url. Secret keys go in the companion credentials.toml; the non-secret *_BASE_URL keys stay in config.toml. To read an API key from the process instead, explicitly reference its variable name with api_key_env.

# ~/.kiki/credentials/credentials.toml
[providers.kimi.env]
KIMI_API_KEY = "sk-xxx"

# config.toml
[providers.kimi.env]
KIMI_BASE_URL = "https://api.moonshot.ai/v1"

Key names per provider:

Key	Applicable provider	Default
KIMI_API_KEY	Kimi / Moonshot	None
KIMI_BASE_URL	Kimi / Moonshot	https://api.moonshot.ai/v1
ANTHROPIC_API_KEY	Anthropic	None
ANTHROPIC_BASE_URL	Anthropic	Follows Anthropic SDK default
OPENAI_API_KEY	OpenAI (openai and openai_responses)	None
OPENAI_BASE_URL	OpenAI (openai and openai_responses)	https://api.openai.com/v1
GOOGLE_API_KEY	Google GenAI (google-genai)	None
GOOGLE_GEMINI_BASE_URL	Google GenAI (google-genai)	https://generativelanguage.googleapis.com
GOOGLE_VERTEX_BASE_URL	Vertex AI (vertexai)	https://aiplatform.googleapis.com when no location is set or the location is global. https://aiplatform.us.rep.googleapis.com for us and https://aiplatform.eu.rep.googleapis.com for eu. https://<location>-aiplatform.googleapis.com for another location. An API key and project ADC use the same host.
VERTEXAI_API_KEY	Vertex AI (vertexai)	None
GOOGLE_CLOUD_PROJECT	Vertex AI, together with GOOGLE_CLOUD_LOCATION	None
GOOGLE_CLOUD_LOCATION	Vertex AI, together with GOOGLE_CLOUD_PROJECT	None

WARNING

GOOGLE_APPLICATION_CREDENTIALS (path to a service account JSON file) is read directly by the Google SDK through the standard ADC flow. Project, location, and base URL values still come from the provider's config sub-table; api_key_env opts in only the named API key, not other shell variables.

For the full provider type and field reference, see Providers and models.

OAuth and managed services

This group of variables redirects OAuth authentication and managed service endpoints to a self-hosted or test environment. They are not needed for everyday use.

Variable	Purpose	Default
KIKI_CODE_OAUTH_HOST	OAuth auth host; highest priority	Falls back to KIKI_OAUTH_HOST when unset
KIKI_OAUTH_HOST	OAuth auth host; fallback for KIKI_CODE_OAUTH_HOST	Falls back to https://auth.kimi.com when unset
KIKI_CODE_BASE_URL	Managed API base URL used after OAuth login	https://api.kimi.com/coding/v1

WARNING

KIKI_CODE_BASE_URL (OAuth-managed service, targeting kimi.com) and KIMI_BASE_URL (direct API key connection, targeting moonshot.ai) are two distinct variables. Use each one in its appropriate context.

Define a model from environment variables (KIKI_MODEL_*)

Want to switch models for testing without touching config.toml? When KIKI_MODEL_NAME is set, the CLI synthesizes a temporary provider and model alias from the KIKI_MODEL_* variables in memory — nothing is written back to the config file. These variables take priority over default_model in config.toml, but the -m <alias> option at startup still has the highest priority.

export KIKI_MODEL_NAME="kimi-for-coding"
export KIKI_MODEL_API_KEY="YOUR_API_KEY"
export KIKI_MODEL_BASE_URL="https://api.example.com/v1"
export KIKI_MODEL_MAX_CONTEXT_SIZE="262144"
export KIKI_MODEL_CAPABILITIES="image_in,thinking"
kiki

Complete variable list:

Variable	Required	Purpose	Default
KIKI_MODEL_NAME	Yes (also the enable switch)	Model id sent to the API	—
KIKI_MODEL_API_KEY	Yes	API key	—
KIKI_MODEL_PROVIDER_TYPE	No	Provider type: kimi, anthropic, openai	kimi
KIKI_MODEL_BASE_URL	No	API base URL	Each type has its own default
KIKI_MODEL_MAX_CONTEXT_SIZE	No	Maximum context length (tokens)	262144 (256 K)
KIKI_MODEL_CAPABILITIES	No	Comma-separated capability tags, unioned with auto-detected capabilities	image_in,thinking
KIKI_MODEL_DISPLAY_NAME	No	Name shown in /model	Falls back to KIKI_MODEL_NAME
KIKI_MODEL_MAX_OUTPUT_SIZE	No	Per-request output cap (anthropic only); when set, overrides the built-in Claude ceiling	Model default
KIKI_MODEL_REASONING_KEY	No	Reasoning field name override (openai only)	Auto-detected
KIKI_MODEL_THINKING_EFFORT	No	Thinking effort for the synthesized temporary model: low/medium/high/xhigh/max; only read when KIKI_MODEL_NAME is set (distinct from the same-named runtime switch below)	—
KIKI_MODEL_ADAPTIVE_THINKING	No	Force adaptive thinking on or off (anthropic only)	Inferred from model name

If KIKI_MODEL_NAME is set but a required variable is missing, startup fails immediately with a clear error message.

Note that KIKI_MODEL_THINKING_EFFORT is read in two independent places: here, to set the temporary model's effort when KIKI_MODEL_NAME is set; and as a global runtime switch (below) that forces the effort on the wire for every kimi-provider request, regardless of KIKI_MODEL_NAME.

Runtime switches

Switches that control the behavior of subsystems such as background tasks, the built-in search and retrieval module, and the plugin marketplace:

Variable	Purpose	Valid values
KIKI_PASSWORD	Set a parallel auth credential for the kiki web local server, valid alongside the bearer token; recommended when binding the server beyond loopback — see Local server and API	Any non-empty string; when unset, only the token is valid
KIKI_BACKGROUND_KEEP_ALIVE_ON_EXIT	Whether to keep background tasks when the session closes; takes higher priority than config.toml. The default is to stop them on exit	Truthy: 1/true/yes/on; falsy: 0/false/no/off
KIKI_BACKGROUND_MAX_RUNNING_TASKS	Cap on concurrently running background tasks; takes higher priority than [background] max_running_tasks in config.toml (unset means no cap)	Positive integer; invalid values are ignored
KIKI_IMAGE_MAX_EDGE_PX	Longest-edge ceiling (px) for image compression; takes higher priority than [image] max_edge_px in config.toml (default 2000)	Positive integer; invalid values are ignored
KIKI_IMAGE_READ_BYTE_BUDGET	Per-image byte budget for model-initiated image reads (ReadMediaFile default reads); takes higher priority than [image] read_byte_budget in config.toml (default 262144, i.e. 256 KB)	Positive integer; invalid values are ignored
KIKI_PLUGIN_MARKETPLACE_URL	Set the plugin marketplace JSON loaded by /plugins; takes priority over [plugins] marketplace_url	http:// or https:// URL, file:// URL, or local path; unset or blank does not load a remote catalog
KIKI_SUBAGENT_TIMEOUT_MS	Maximum wall-clock time (ms) a single subagent (AgentRun) may run; takes higher priority than [subagent] timeout_ms in config.toml (default 7200000, i.e. 2 hours)	Positive integer; invalid values fall back to the config or default
KIKI_IDENTITY_NAME	Display name the agent calls itself in the system prompt; takes higher priority than [identity] name in config.toml and is never written back to it	Any non-empty string; blank values read as unset
KIKI_IDENTITY_SLUG	Protocol identifier for the User-Agent product token sent to third-party providers and the MCP client name; takes higher priority than [identity] slug. Derived from the name when unset	Any non-empty string; normalized to lowercase with non-alphanumeric runs folded to -
KIKI_BUILTIN_PRODUCT_SKILLS	Whether the built-in skills documenting Kiki itself are offered to the model; takes higher priority than builtin_product_skills in config.toml (default enabled)	Truthy: 1/true/yes/on; falsy: 0/false/no/off
KIKI_TUI_FULL_SCREEN	Enable the experimental fullscreen alternate-screen UI: scrollable transcript viewport, mouse text selection, clickable links, and Ctrl-Shift-F transcript search	1 enables it; anything else keeps the regular inline UI
KIKI_EXPERIMENTAL_TASK_WAIT	Whether the model is given the TaskWait tool, which waits for background tasks inside the current turn instead of ending it (enabled by default)	Truthy: 1/true/yes/on; falsy: 0/false/no/off
KIKI_EXPERIMENTAL_WORK_PRESETS	Control space-local Work modes and their explicit package setup (default on); takes precedence over [experimental] work_presets — see Spaces and work modes	Truthy: 1/true/yes/on; falsy: 0/false/no/off
KIKI_MCP_CONFIG_PATH	MCP config file injected by an external orchestrator and loaded read-only by the server started via kiki web. Must be set together with KIKI_MCP_AGENT_PROFILE_HOME and KIKI_MCP_CONFIG_READ_ONLY; an incomplete set fails startup	Absolute path
KIKI_MCP_AGENT_PROFILE_HOME	Agent-profile root directory injected by an external orchestrator, used together with KIKI_MCP_CONFIG_PATH; the three KIKI_MCP_* catalog variables must always be set as a set	Absolute path
KIKI_MCP_CONFIG_READ_ONLY	Read-only marker for the injected catalog; must be 1 — the server never writes back to the injected config or profiles	1
KIKI_MCP_STARTUP_TIMEOUT_MS	Global default connection timeout (ms) for all MCP servers; takes higher priority than [mcp] startup_timeout_ms in config.toml, but a per-server startupTimeoutMs in mcp.json still wins (default 30000)	Integer from 1 to 2147483647; invalid values are ignored
KIKI_MCP_TOOL_TIMEOUT_MS	Global default single tool-call timeout (ms) for all MCP servers; takes higher priority than [mcp] tool_timeout_ms in config.toml, but a per-server toolTimeoutMs in mcp.json still wins (default 60000)	Integer from 1 to 2147483647; invalid values are ignored
KIKI_LOOP_MAX_STEPS_PER_TURN	Maximum Agent steps per turn; takes higher priority than [loop_control] max_steps_per_turn in config.toml (unset or 0 means unlimited)	Non-negative integer; invalid values are ignored
KIKI_LOOP_MAX_ATTEMPTS_PER_STEP	Maximum total attempts for a failing step (including the initial attempt); takes higher priority than [loop_control] max_attempts_per_step in config.toml (default 5)	Non-negative integer; invalid values are ignored
KIKI_INFINITE_RETRY	Retry failed LLM requests indefinitely, including turn steps, compaction, HTTP 400/404, and quota errors. Waits use exponential backoff (capped at 32 s) and honor Retry-After. Does not override cancellation, local admission denials, observed output or tool execution, retry = false, or per-request retry: 'never'; the one-use Continue. request is never retried. Context overflow still uses context recovery. Intended for unattended evaluations against temporarily failing endpoints	Truthy: 1/true/yes/on; falsy: 0/false/no/off
KIKI_TOKEN_COUNTING_STRATEGY	Which context token count is reported externally (the context-size display); takes higher priority than [token_counting] strategy in config.toml (default measured+estimated)	measured+estimated, measured, estimated (case-insensitive); invalid values are ignored
NB_SEARCH_CONFIG	Path to a canonical JSON configuration for the built-in search and retrieval module, loaded before Kiki's [nb_search] patch	File path
NB_SEARCH_HOME	Data directory for the built-in search and retrieval module	Directory path
NB_SEARCH_JOBS_ROOT	Durable job directory for the built-in search and retrieval module	Directory path
NB_SEARCH_LOG_LEVEL	Log level for the built-in search and retrieval module	error, warn, info, or debug
NB_SEARCH_RETENTION_HOURS	Retention period for durable search and fetch job results	Positive integer
NB_SEARCH_EXA_API_KEY	Credential used by the built-in exa.default provider instance	Non-blank string
NB_SEARCH_TAVILY_API_KEY	Credential used by the built-in tavily.default provider instance	Non-blank string
NB_SEARCH_JINA_API_KEY	Optional credential used by the built-in jina-reader.default fetch provider instance	Non-blank string
KIKI_EXPERIMENTAL_AUTO_SESSION_TITLE	Whether Kiki writes session titles on its own; takes precedence over the [experimental] entry and KIKI_EXPERIMENTAL_FLAG (default on). The chosen triggers still decide when, and with no title model Kiki sends no title request at all — see session_title	Enable: 1/true/yes/on; disable: 0/false/no/off
KIKI_EXPERIMENTAL_FLAG	Enable all registered experimental features for this process; a per-feature KIKI_EXPERIMENTAL_<NAME> variable or an explicit entry in the [experimental] section of config.toml takes precedence over it	1, true, yes, on
KIKI_SHELL_PATH	Override the Git Bash path on Windows (used when auto-detection fails)	Absolute path
KIKI_MODEL_MAX_COMPLETION_TOKENS	Hard cap on max_completion_tokens per LLM step; applies to the kimi provider only	Positive integer; 0 or negative disables clamping
KIKI_MODEL_TEMPERATURE	Sampling temperature for every request; applies to the kimi provider only (global — independent of KIKI_MODEL_NAME)	Number, e.g. 0.3
KIKI_MODEL_TOP_P	Nucleus-sampling top_p for every request; applies to the kimi provider only (global)	Number, e.g. 0.95
KIKI_MODEL_THINKING_EFFORT	Force a specific thinking effort on the wire (thinking.effort), bypassing the model's declared support_efforts; applies to the kimi provider only, and only while Thinking is on	An effort value, e.g. max
KIKI_MODEL_THINKING_KEEP	Preserved-thinking passthrough; on kimi sent as thinking.keep, on anthropic (Claude and Kimi's Anthropic-compatible mode) sent as a context_management clear_thinking_20251015 edit (enabling keep routes Anthropic requests to the beta Messages API); overrides [thinking] keep (which defaults to "all"); only injected while Thinking is on	A value the API accepts, e.g. all; an off-value (false/0/no/off/none/null) disables it
KIKI_DISABLE_CRON	Disable the scheduled-task tool (a Cron call with action: "create" is refused; existing tasks do not fire)	1 to disable

Subagent concurrency has no environment-variable override. Configure [subagent] with max_direct_children and max_total_subagents; their defaults are 16 and 0 (unlimited), respectively.

[subagent].default_model supplies a model only when dispatch parameters and effective pins do not. It never inherits the caller's model, and neither it nor a forced environment value can bypass a profile's hard model rules. [subagent].default_effort was removed and is no longer read — startup warns about it; set an effort pin on the profile, route, or caller lease, or let the selected model use its own default.

Diagnostic logs

These variables control log level and file rotation, read once at process startup:

Variable	Purpose	Default
KIKI_LOG_LEVEL	Log level: off, error, warn, info, debug	info
KIKI_LOG_GLOBAL_MAX_BYTES	Maximum bytes per global log file	6291456 (6 MB)
KIKI_LOG_GLOBAL_FILES	Number of global log files to retain	5
KIKI_LOG_SESSION_MAX_BYTES	Maximum bytes per session log file	5242880 (5 MB)
KIKI_LOG_SESSION_FILES	Number of session log files to retain	3

System environment variables

The CLI also reads several standard system variables to detect the runtime environment; it does not modify them:

• HOME: used to resolve the default data path
• VISUAL, EDITOR: external editor command (VISUAL takes precedence)
• PATH: used to locate dependencies such as rg, fd, fdfind, and git; on Windows, Git Bash detection checks each git.exe found on PATH, including package-manager shims such as Scoop
• NO_COLOR, FORCE_COLOR: control color output (following the no-color.org convention)
• CI: when non-empty and not "0", disables theme detection and falls back to the dark theme
• TERM_PROGRAM, TERM, TMUX: detect terminal features and notification support
• DISPLAY, WAYLAND_DISPLAY, XDG_SESSION_TYPE: detect Linux graphical sessions (for clipboard and image features)
• WSL_DISTRO_NAME, WSLENV: detect WSL for the clipboard PowerShell bridge
• LOCALAPPDATA: used on Windows as a fallback when probing for the Git Bash installation path

HTTP proxy

Kiki honors the standard proxy environment variables for all outbound traffic — model API calls, MCP servers, web tools, sign-in, and update checks:

• HTTP_PROXY / http_proxy: proxy for http:// requests
• HTTPS_PROXY / https_proxy: proxy for https:// requests
• ALL_PROXY / all_proxy: fallback proxy used when the scheme-specific variable is unset; this is where a SOCKS proxy is usually set
• NO_PROXY / no_proxy: comma-separated hosts that bypass the proxy

Both HTTP(S) and SOCKS proxies are supported. A SOCKS proxy is recognized by its scheme — socks5://, socks5h://, socks4://, or socks:// (an alias for socks5://) — and is typically set via ALL_PROXY (the form used by tools like Clash and V2RayN). An HTTP(S) proxy takes precedence over ALL_PROXY for HTTP/HTTPS traffic.

The proxy is applied only when one of these variables is set; otherwise connections are made directly. Loopback hosts (localhost, 127.0.0.1, ::1) always bypass the proxy, so a local server such as a localhost MCP server keeps working when a proxy is configured — add your own internal hosts to NO_PROXY to exempt them too.

Stdio MCP servers that run as Node child processes honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY automatically when the child's Node version supports NODE_USE_ENV_PROXY (Node ≥ 22.21 or ≥ 24.5); SOCKS proxying applies to Kiki's own traffic only.

Next steps

• Config overrides — how environment variables, CLI options, and the config file interact by priority
• Data locations — directory structure affected by KIKI_HOME
• Providers and models — full connection examples per provider type