Environment Variables

Kolega Code reads configuration from CLI flags, exported environment variables, and saved Settings. It does not automatically load the target project’s .env file for its own provider/model/API-key configuration. This page lists the environment variables it understands when they are explicitly present in the Kolega Code process environment.

Precedence

For any given setting, the first available source wins:

1. CLI flags (e.g. --provider, --model)
2. Exported process environment variables
3. Saved Settings (settings.json)

Kolega Code requires an explicit provider/model selection from flags, exported environment variables, or saved settings. API key variables alone are not a model selection source.

Note

A project .env file is treated as part of the project being edited. Kolega Code will not read it for its own LLM configuration. For persistent credentials, use Settings. For automation, export environment variables in the shell or CI process that launches Kolega Code.

API keys

Set the variable for each provider you use. Only the providers backing your active model roles are required.

API key variables provide credentials only. They do not select the active provider or model.

Variable	Provider
ANTHROPIC_API_KEY	Anthropic
OPENAI_API_KEY	OpenAI
GOOGLE_API_KEY	Google
MISTRAL_API_KEY	Mistral AI (native API)
GROQ_API_KEY	Groq
TOGETHER_API_KEY	Together.ai
FIREWORKS_API_KEY	Fireworks.ai
XAI_API_KEY	x.ai
DASHSCOPE_API_KEY	DashScope (Alibaba)
MOONSHOT_API_KEY	Moonshot
MINIMAX_API_KEY	MiniMax
DEEPSEEK_API_KEY	DeepSeek
ZAI_API_KEY	Z.AI (GLM Coding Plan)
KIMI_CODING_API_KEY	Kimi Coding Plan
OLLAMA_API_KEY	Ollama Cloud
CLOUDFLARE_API_TOKEN	Cloudflare Workers AI (also needs CLOUDFLARE_ACCOUNT_ID)
OPENROUTER_API_KEY	OpenRouter
TINKER_API_KEY	Thinking Machines — both the thinking_machines (Anthropic-compatible) and tinker (native SDK) providers
PERPLEXITY_API_KEY	Perplexity Agent API
REFUSELESS_API_KEY	Refuseless

The local llama provider needs no key. The zai key authenticates against Z.AI’s Anthropic-compatible endpoint (it is the key Z.AI also documents as ANTHROPIC_AUTH_TOKEN). The kimi_coding key authenticates against the Kimi Coding Plan’s separate Anthropic-compatible endpoint (https://api.kimi.com/coding/), which is distinct from the standard Moonshot API used by the moonshot provider. The OLLAMA_API_KEY key authenticates against Ollama Cloud’s direct API (https://ollama.com/v1 for OpenAI-compatible requests). The OPENROUTER_API_KEY key authenticates against the OpenRouter gateway (https://openrouter.ai/api/v1). The PERPLEXITY_API_KEY key authenticates against the Perplexity Agent API (https://api.perplexity.ai/v1). The REFUSELESS_API_KEY key authenticates Refuseless Chat Completions requests at https://api.refuseless.com/v1. An exported key overrides the Refuseless key saved in Settings; it does not select a provider or model. The MISTRAL_API_KEY key authenticates against Mistral’s own native Chat Completions API (https://api.mistral.ai/v1). Select mistral together with a model such as mistral-medium-3-5; the key alone does not select a model. This is a native Mistral key, not an OpenRouter or other gateway key. As with other provider keys, an exported MISTRAL_API_KEY takes precedence over a saved Settings key. On Medium 3.5, Small 4, and Large 4, KOLEGA_CODE_THINKING_EFFORT accepts none (default) or high; Large 3, Ministral 3 and Codestral do not expose this control. latest aliases can change. See Providers and Models for image support and local token-budgeting limitations.

Mistral catalog

Variable	Purpose
KOLEGA_CODE_MISTRAL_CATALOG	Read the refreshed model cache from this path instead of the state directory.
KOLEGA_CODE_DISABLE_MISTRAL_CATALOG	Ignore any refreshed cache and use only the catalog bundled with this release.

The refresh endpoint is authenticated, so kolega-code models refresh --provider mistral requires MISTRAL_API_KEY or a key saved in Settings.

Ollama Cloud catalog

Variable	Purpose
KOLEGA_CODE_OLLAMA_CLOUD_CATALOG	Read the refreshed model cache from this path instead of the state directory.
KOLEGA_CODE_DISABLE_OLLAMA_CLOUD_CATALOG	Ignore any refreshed cache and use only the catalog bundled with this release.

Cloudflare Workers AI

Variable	Purpose
CLOUDFLARE_ACCOUNT_ID	The 32-character account ID that scopes Workers AI requests. Overrides the Account ID saved under Settings → Providers. Required whenever a Cloudflare model is in use.
CLOUDFLARE_AI_GATEWAY_ID	Optional. Route Workers AI requests through this AI Gateway (sent as the cf-aig-gateway-id header).
KOLEGA_CODE_CLOUDFLARE_WORKERS_AI_CATALOG	Read the refreshed model cache from this path instead of the state directory.
KOLEGA_CODE_DISABLE_CLOUDFLARE_WORKERS_AI_CATALOG	Ignore any refreshed cache and use only the catalog bundled with this release.

CLOUDFLARE_API_TOKEN must be an API token with the Workers AI Read permission; the Global API Key does not work. kolega-code models refresh --provider cloudflare_workers_ai needs both the token and the account ID (from the environment or Settings).

OpenRouter tuning

All optional; unset means Kolega Code sends nothing for that field.

Variable	Purpose
KOLEGA_CODE_OPENROUTER_PROVIDER_ORDER	Comma-separated upstream provider slugs to try in order (OpenRouter provider.order).
KOLEGA_CODE_OPENROUTER_PROVIDER_ONLY	Comma-separated upstream provider slugs to restrict routing to (OpenRouter provider.only).
KOLEGA_CODE_OPENROUTER_CATALOG	Read the refreshed model cache from this path instead of the state directory.
KOLEGA_CODE_DISABLE_OPENROUTER_CATALOG	Ignore any refreshed cache and use only the catalog bundled with this release.

Model selection

Each role can be configured independently. Provider and model are always set together — naming one without the other is an error. Nothing is inferred from a model id and no model is defaulted from a provider, because the same id can be served by different providers on different credentials.

Variable	Role
KOLEGA_CODE_PROVIDER / KOLEGA_CODE_MODEL	Main (long-context) coding model
KOLEGA_CODE_FAST_PROVIDER / KOLEGA_CODE_FAST_MODEL	Fast utility model
KOLEGA_CODE_THINKING_EFFORT	Model-specific thinking effort
KOLEGA_CODE_EDIT_PROTOCOL	Optional model-facing edit override: search_replace, codex_apply_patch, or claude_code; otherwise the model catalogue preference or claude_code fallback is used
KOLEGA_CODE_CUSTOM_ENDPOINTS	JSON object of custom endpoint definitions, merged over settings.json per endpoint id (never persisted)
KOLEGA_CODE_ENDPOINT_URL	Base URL defining the ephemeral custom:cli endpoint
KOLEGA_CODE_ENDPOINT_STYLE	Wire style for that endpoint: openai_chat, openai_responses, or anthropic (default openai_chat)
KOLEGA_CODE_ENDPOINT_API_KEY	Optional credential for that endpoint
KOLEGA_CODE_ENDPOINT_CONTEXT / KOLEGA_CODE_ENDPOINT_MAX_OUTPUT	Context window / max output tokens for that endpoint (defaults 32768 / 8192)
KOLEGA_CODE_ENDPOINT_TEMPERATURE	Sampling temperature for that endpoint (0–2; default 1.0)
KOLEGA_CODE_ENDPOINT_VISION	Non-empty marks that endpoint’s models as vision-capable
KOLEGA_CODE_ENDPOINT_THINKING	Thinking-effort mode for that endpoint (thinking_toggle, openai_reasoning_effort, openai_responses_reasoning, anthropic_budget)
KOLEGA_CODE_ENDPOINT_REASONING	Reasoning replay field for that endpoint: auto, reasoning_content, reasoning, or off

These outrank the Fast slot saved in Settings. Full precedence per role: CLI flag > environment variable > saved slot > the active model.

See Providers & Models for what each role does.

Per-agent models

Give an individual agent its own model. <ROLE> is one of PLANNING, BUILDING, INVESTIGATION, GENERAL, or BROWSER. A role with no override inherits the main model. These also override anything saved in the Settings screen’s Agent Models category.

Variable	Purpose
KOLEGA_CODE_<ROLE>_PROVIDER	Provider for that agent (e.g. KOLEGA_CODE_INVESTIGATION_PROVIDER)
KOLEGA_CODE_<ROLE>_MODEL	Model for that agent
KOLEGA_CODE_<ROLE>_EFFORT	Thinking effort for that agent

The BROWSER role requires a vision-capable model. An incompatible explicit or inherited model is never replaced automatically; dispatching the browser agent fails with a configuration error until KOLEGA_CODE_BROWSER_PROVIDER and KOLEGA_CODE_BROWSER_MODEL (or the equivalent Settings override) select a model with vision support.

State & environment

Variable	Purpose
KOLEGA_CODE_STATE_DIR	Override where settings and sessions are stored
KOLEGA_CODE_ENVIRONMENT	Environment label attached to tracing/metadata (default development)
KOLEGA_CODE_NO_DIAGNOSTICS	Set to any value to disable the local diagnostics log and responsiveness watchdog
KOLEGA_CODE_COMPRESSION_THRESHOLD	Context-window usage percent that triggers automatic history compression (10–100, default 95; 100 disables proactive compression; over-limit recovery and explicit context caps remain enforced)
KOLEGA_CODE_SUBAGENTS	Sub-agent dispatch (dispatch_agent) master switch: on or off (default on). Useful for headless or CI runs; the --subagents flag takes precedence
KOLEGA_CODE_SKILLS	Agent Skills master switch: on or off (default on). When off, skills are not discovered, the skill tool is not exposed, and /skills reports that Agent Skills are disabled; the --skills flag takes precedence

Live sharing

Variable	Purpose
KOLEGA_CODE_SHARE_ALLOWED_ORIGINS	Comma-separated exact HTTP(S) origins permitted in addition to the local /share origin, such as https://share.example.com or http://jump-host:8765. Set before launching Kolega Code. Wildcards, credentials, paths, queries and fragments are rejected. Each origin also permits its hostname; tokens remain required.

Loopback and /share lan links need no additional origin. Set this only for tunnels you control; see live sharing. Forwarded headers cannot expand the allowlist.

Streaming & retries

A streaming response is bounded by an idle budget, not by a single socket read. While waiting for stream events, the status line says Waiting for response…. This is informational: the model may still be working, and silence alone does not indicate a connection problem. The waiting label clears when events resume, even if they contain no visible text. Only an actual timeout or error triggers failure handling. Failure details stay in the diagnostics rather than the narrow status strip. These knobs adjust the waiting and retry budgets:

Variable	Purpose
KOLEGA_STREAM_FIRST_CHUNK_TIMEOUT	Seconds allowed for request setup and the first stream event before timing out (default 90)
KOLEGA_STREAM_IDLE_TIMEOUT	Seconds of silence between stream events after the first arrives (default 300)
KOLEGA_STREAM_IDLE_HEARTBEAT	Seconds between “Waiting for response…” status updates while the stream is silent (default 15)
KOLEGA_LLM_RETRY_BUDGET	Total seconds one turn may spend retrying transient failures (default 360). A stall that produced no output at all is retried only once

Each retry is written to the transcript, not just the status line, so failures stay visible after the fact. Timeouts say Response timed out — retrying (1/3) in 8s…; other transient failures, including rate limits and provider overload, say Retrying request (1/3) in 8s….

Gateway

The messaging gateway (kolega-code gateway) is configured from settings.json like everything else — run kolega-code gateway telegram setup to save the bot token, your allowlist, and switch the adapter on. The stored keys live under the gateway section (plus the top-level telegram_bot_token); every key has a built-in default, so only what you change needs to be stored:

Setting	Default	Purpose
telegram_bot_token (top level)	—	The Telegram bot token from @BotFather, saved by gateway telegram setup.
gateway.adapter	echo	Messaging adapter to run (telegram).
gateway.project	~/kolega-code-workspace	Working directory for gateway sessions.
gateway.allowed_users	[] (paired users only; none paired = locked)	Trusted Telegram operators, as quoted positive numeric user IDs. Combined with valid persisted pairing approvals; an empty list never means public access.
gateway.group_ids	[] (all, mention-gated)	Group chat IDs as quoted signed nonzero numeric strings. Group restrictions also require sender authorization; they never authorize group members on their own.
gateway.pairing_enabled	false	Let unknown senders request a pairing code, including the first user. Local CLI approval is required before agent access; with no authorized users this is pairing-only, not public access.
gateway.pairing_code_ttl_seconds	3600	Pairing-code lifetime in seconds.
gateway.permission_mode	ask	Session permission mode: ask or auto. ask confirms tools in the requesting chat, not with a separate machine owner; trusted users can approve their own tools and switch to auto.
gateway.request_timeout_seconds	600	How long a permission/question prompt waits for a tap.
gateway.max_sessions	50	Live-session cache size.
gateway.session_idle_ttl_seconds	3600	Idle session eviction (null disables).
gateway.edit_throttle_seconds	1	Minimum interval between edit-in-place streaming updates.
gateway.telegram_proxy	—	Optional HTTP proxy for the Telegram connection.
stt_enabled (top level)	false	Transcribe voice audio remotely (Tools → Voice transcription).
stt_provider (top level)	groq	Remote speech-to-text provider: groq or openai. The selected provider reuses its API key from the Providers page or environment.
stt_model (top level)	provider default	Provider-specific model override (whisper-large-v3-turbo for Groq; gpt-transcribe for OpenAI).

All admitted users are trusted operators of the local agent, not sandboxed guests. Admitted group participants share their chat’s session and control surface. Unknown senders cannot run commands, approve tools, or cause attachment downloads or transcription.

For explicit setup, use kolega-code gateway telegram setup --allow '123456789' with your numeric user ID. Token-only setup saves configuration but warns when no operators are authorized; it never implicitly enables pairing. Omitting --allow preserves configured IDs; explicit --allow '' clears only that list. To onboard the first user without a configured ID, enable pairing in Settings → Gateway, start/restart the daemon, DM the bot for a code, locally run gateway pairing list and review the numeric sender ID, confirm and approve the code with gateway pairing approve <code>, then DM again. Prefix those commands with kolega-code; see the full pairing workflow.

Configured IDs and valid approvals in gateway_allowlist.json form a union. Clearing either source does not revoke users in the other; disabling pairing does not revoke approvals. Settings-based access changes require restart, whereas persisted approvals are reread dynamically. For exclusive-owner lockdown, stop the gateway, inspect both files in its state directory, remove unwanted approvals and configure the owner’s ID, then restart. Preserve unrelated settings and credentials; see migration and lockdown.

Malformed access settings produce a field-specific error rather than being silently ignored: gateway must be an object, allowed_users and group_ids must be lists of nonempty strings, and pairing_enabled must be a JSON boolean. Telegram IDs use ASCII decimal digits: positive user IDs such as ["123456789"], signed nonzero group IDs such as ["-1001234567890"]. Numbers without quotes, handles, wildcards, blank entries, mixed-type lists, and "false" instead of false are invalid. Missing keys and empty lists are valid; surrounding ID whitespace is trimmed and duplicates are removed. Repair the named field, not by deleting all settings or credentials. Invalid CLI/TUI edits are rejected before saving a replacement token.

After upgrading, restart old daemons: empty-list deployments become locked or pairing-only unless valid approvals authorize users. gateway status reports the running heartbeat’s locked, pairing-only, or restricted policy, configured/paired counts, and pairing flag — not un-applied settings changes. Older heartbeats show access policy unknown; restart/update to verify. Local echo is reported separately; its standard local owner allowance does not open Telegram access.

Web search

The web_search tool defaults to the keyless DuckDuckGo backend. Set a backend explicitly when you want a cloud provider or a self-hosted SearXNG instance.

Variable	Purpose
KOLEGA_CODE_WEB_SEARCH_MODE	Web tool mode: auto (hosted server-side search when the model supports it, else client tools), hosted, client, or off
KOLEGA_CODE_WEB_SEARCH_BACKEND	Backend for web_search: duckduckgo, firecrawl, tavily, or searxng
FIRECRAWL_API_KEY	Optional Firecrawl key for higher rate limits
TAVILY_API_KEY	Tavily API key
SEARXNG_BASE_URL	Base URL for a self-hosted SearXNG instance

Browser automation

Local browser automation needs no credentials. Hosted sandbox deployments can connect the same browser agent to Browserless.

Variable	Purpose
BROWSERLESS_API_KEY	Browserless cloud API token
BROWSERLESS_WS_ENDPOINT	Optional cloud or self-hosted WebSocket endpoint
BROWSERLESS_REGION	Cloud region used when no endpoint is supplied: sfo, lon, or ams
BROWSERLESS_PROTOCOL	Connection protocol: cdp (default) or playwright
BROWSERLESS_TIMEOUT_MS	Optional maximum Browserless session duration; must fit the account plan
BROWSER_CONNECT_TIMEOUT_MS	Browser transport connection timeout (default 30000 ms)

Custom endpoint query parameters are preserved, including Browserless proxy, stealth, profile, and recording options. If BROWSERLESS_TIMEOUT_MS is unset, Browserless applies the account’s default session duration.

Telemetry (Langfuse)

Optional Langfuse tracing of LLM usage.

Kolega Code uses the Langfuse Python SDK v4. Langfuse Cloud always supports it; a self-hosted Langfuse server must run a release that supports the v4 SDK.

Variable	Purpose
LANGFUSE_HOST	Langfuse host URL
LANGFUSE_PUBLIC_KEY	Langfuse public key
LANGFUSE_SECRET_KEY	Langfuse secret key

About project .env files

Kolega Code does not automatically load a .env file from the project directory. That file commonly belongs to the app being edited, so consuming it as Kolega Code configuration can accidentally pick up unrelated application secrets such as OPENAI_API_KEY.

Use one of these instead:

one-off shell configuration

export MOONSHOT_API_KEY=...
export KOLEGA_CODE_PROVIDER=moonshot
export KOLEGA_CODE_MODEL=kimi-k2.7-code
kolega-code

Or save the provider, model, and API key in the TUI Settings screen. Settings are the recommended persistent configuration path for interactive use.

Caution

Keep project .env files out of version control — they often hold application secrets. Add them to your .gitignore.