Settings & API Keys

Kolega Code keeps a small amount of state on your machine: your provider/model selection, API keys, and saved sessions.

First-run onboarding

When the TUI starts without a working model configuration, it opens a short setup wizard. Choose either Sign in with ChatGPT or Use an API key, select the model and thinking effort, review the result, and finish. The API-key path detects credentials already supplied through the environment or local settings, so you do not need to paste the key again.

The final step includes an optional Test Connection action. It sends only Reply with OK. to the selected model, with no tools and a 32-token completion limit. This is a real provider request, so it can be billable. Finishing persists the complete setup at once; going back or choosing Skip for now does not write a partial draft. Skipping lasts only for the current TUI session.

The Settings screen

The Settings sidebar tab is a compact read-only summary. Select Open Settings, or run /settings, to open the full-screen editor. Its category rail separates the controls into:

Category	What it configures
Providers	API keys and ChatGPT sign-in for every model provider, plus per-provider connection testing
Models	Provider, model, thinking effort, and the fast/thinking model slots
Agent Models	Optional provider/model/effort override for each agent role
Tools	Web-search backend and global LSP toggle
MCP Servers	Global and trusted-project MCP server management
Appearance	TUI theme

Provider, model, agent, tool, credential, and appearance changes stay in a draft until you select Apply Changes. Kolega Code validates the complete candidate before replacing the saved settings and rebuilding the agent. If validation fails, the previous settings remain saved and the draft stays open for correction. Closing a changed draft asks before discarding it. Theme changes preview immediately but follow the same Apply/discard behavior.

Providers lists every model provider with its current credential status — present via <ENV_VAR>, present in local settings, signed in as …, or missing — so you can see at a glance what you are set up for. Select a provider to edit its credential.

The API-key input never echoes a saved secret. Leave it blank to retain the current key, paste a value to replace it, or select Remove Stored Key to stage its removal. Environment variables are only reported, never changed by the TUI. ChatGPT sign-in and sign-out are staged the same way.

Keys are staged per provider, so you can set up several providers before pressing Apply — useful when a fast/thinking slot or an agent role runs on a provider other than your main model. Credentials are independent of model selection: changing the provider under Models does not touch any key.

Test Connection probes the selected provider rather than the active model, using that provider’s configured model where there is one and its default otherwise — so you can check a credential for a provider you are not currently running on. It has the same small, potentially billable request behavior as the onboarding test.

MCP actions are the exception to the global Apply button: their server config, verification, enable/disable state, trust, and OAuth actions save immediately. Settings labels this explicitly and confirms trust, deletion, and token removal.

When you switch models, the thinking effort resets to the new model’s default.

A saved selection is the default for all agent model roles. Existing environment variables and --provider / --model flags continue to override it — see Providers & Models for resolution order. API key environment variables are credentials only; they do not choose the active provider or model.

The Agent Models category lets you give individual agents (planning, building, investigation, general, browser) their own provider, model, and effort. Leave a role on Default to inherit the active model. See Per-agent models.

The Browser role only accepts vision-capable model overrides. If it inherits a non-vision active model, Settings allows the inheritance but warns that the browser agent is unavailable until you choose a compatible Browser model.

The Tools category configures web access. The Mode select picks who searches: auto (default) uses the provider’s hosted server-side web search when the model supports it and the client tools otherwise; hosted, client, and off pin one behavior (see the tools overview). The backend selects for the client web_search tool: DuckDuckGo is the default and needs no key. Firecrawl can also run without a key, with an optional key for higher rate limits. Tavily requires a key, and SearXNG requires the base URL of your self-hosted instance. The same settings can be supplied with KOLEGA_CODE_WEB_SEARCH_MODE, KOLEGA_CODE_WEB_SEARCH_BACKEND, FIRECRAWL_API_KEY, TAVILY_API_KEY, and SEARXNG_BASE_URL.

Where settings live

Settings are stored as JSON in your platform’s state directory, in a file named settings.json:

Platform	Default location
macOS	~/Library/Application Support/kolega-code/
Linux	$XDG_STATE_HOME/kolega-code/ (falls back to ~/.local/state/kolega-code/)
Windows	%LOCALAPPDATA%\kolega-code\

Override the location entirely with the KOLEGA_CODE_STATE_DIR environment variable, or per-command with --state-dir.

The file looks like this:

{
  "schema_version": 3,
  "active_provider": "moonshot",
  "active_model": "kimi-k2.7-code",
  "active_thinking_effort": "auto",
  "api_keys": {
    "moonshot": "sk-...",
    "deepseek": "sk-...",
    "tavily": "tvly-..."
  },
  "agent_models": {
    "investigation": {
      "provider": "deepseek",
      "model": "deepseek-v4-flash",
      "thinking_effort": "high"
    }
  },
  "web_search_backend": "tavily",
  "web_search_base_url": null
}

agent_models holds per-agent overrides keyed by role (planning, building, investigation, general, browser); a role that is absent inherits the active model. The field is optional and older schema_version files load unchanged. Cloud web-search keys are stored in api_keys under their backend names (firecrawl or tavily); web_search_base_url is used by SearXNG.

Keys are stored in plaintext

API keys are written to settings.json in plaintext, but the file is created with 0600 permissions (readable and writable only by your user). If you’d rather not store keys on disk at all, supply them via environment variables instead.

State directory layout

• Directorykolega-code/

  • settings.json Provider, model, web search, thinking effort, and API keys (0600)
  • Directorysessions/

    • <session-id>.json One file per saved session

Inspecting your configuration

Use doctor to see, without exposing your key, where each value comes from:

kolega-code doctor --project .

It reports the state directory, whether Textual is installed, your stored active model, and — for the API key — whether it’s present via <ENV_VAR>, present in local settings, or missing. See doctor.