Configuration

AtomCode's config is TOML, supports any number of providers side by side, and lets you switch on the fly. This page explains every field and shows examples for common providers.

Config file location

Default path:

macOS / Linux / HarmonyOS PC: ~/.atomcode/config.toml
Windows: %USERPROFILE%\.atomcode\config.toml

You can also use --config /path/to/config.toml to point at any file. On the first run, if the file is missing, the 3-step wizard walks you through initial setup.

Minimal example

default_provider = "deepseek"

[providers.deepseek]
type = "openai"
api_key = "sk-xxxxxxxxxxxxxxxx"
model = "deepseek-chat"
base_url = "https://api.deepseek.com/v1"
context_window = 64000

This config is enough to launch atomcode and start chatting with DeepSeek.

Top-level fields

Field	Type	Description
`default_provider`	string	Provider used at launch (must match a key under `[providers.*]`)
`default_workdir`	string?	Default working directory. `/cd` writes back here; restored next launch
`providers`	table	Map of provider name to ProviderConfig
`vision_preprocessor_provider`	string?	When the main provider can't see images but the user attaches one, forward it to this provider for OCR / description; the result is spliced back into the prompt as text. See Vision preprocessor

ProviderConfig fields

Fields available under each [providers.xxx] table:

Field	Type	Required	Description
`type`	string	yes	Provider protocol — currently `openai`, `claude`, or `ollama`
`api_key`	string?	conditional	API key. Optional for `ollama`. OAuth providers omit this — the token is read from `~/.atomcode/auth.toml` automatically
`model`	string	yes	Model name, e.g. `deepseek-chat`, `gpt-4o`, `claude-sonnet-4-6`
`base_url`	string	yes	API base URL, pointing at the actual endpoint. e.g. `https://api.deepseek.com/v1`, `http://localhost:11434`
`context_window`	integer	no	Model context window (tokens), default 64000. Default 8000 for `ollama`
`max_tokens`	integer?	no	Max output tokens per response. Defaults to `context_window / 4` when unset
`system_prompt`	string?	no	Override the default system prompt. Rarely needed
`user_agent`	string?	no	Override the HTTP User-Agent — useful when the upstream blocks the default UA

Why default to 64K instead of 128K?

Even when a model advertises 128K+, its effective attention window is usually much smaller. An oversized context triggers "lost in the middle" failures and disables AtomCode's compaction strategy. 64K is empirically the most robust default; bump it yourself if your model is solid at higher values.

Common provider examples

Claude (Anthropic)

[providers.claude]
type = "claude"
api_key = "sk-ant-..."
model = "claude-sonnet-4-6"
context_window = 128000

OpenAI

[providers.openai]
type = "openai"
api_key = "sk-..."
model = "gpt-4o"
context_window = 128000

DeepSeek

[providers.deepseek]
type = "openai"
api_key = "sk-..."
model = "deepseek-chat"
base_url = "https://api.deepseek.com/v1"
context_window = 64000

Zhipu GLM

[providers.glm]
type = "openai"
api_key = "..."
model = "glm-4-plus"
base_url = "https://open.bigmodel.cn/api/paas/v4"
context_window = 128000

Tongyi Qianwen (Qwen)

[providers.qwen]
type = "openai"
api_key = "sk-..."
model = "qwen-plus"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
context_window = 128000

SiliconFlow

[providers.siliconflow]
type = "openai"
api_key = "sk-..."
model = "Qwen/Qwen2.5-72B-Instruct"
base_url = "https://api.siliconflow.cn/v1"

Ollama (local)

[providers.ollama]
type = "ollama"
model = "llama3.2"
base_url = "http://localhost:11434"
context_window = 8000

Heads up

Function-calling support varies a lot across Ollama models; weaker local models may not invoke tools reliably. Prefer the Instruct variants of Qwen2.5 / Llama3.2.

Multiple providers and quick switching

Config files can host any number of providers in parallel:

default_provider = "claude"

[providers.claude]
type = "claude"
api_key = "sk-ant-..."
model = "claude-sonnet-4-6"

[providers.deepseek]
type = "openai"
api_key = "sk-..."
model = "deepseek-chat"
base_url = "https://api.deepseek.com/v1"

[providers.local]
type = "ollama"
model = "qwen2.5:14b"
base_url = "http://localhost:11434"

In the TUI, switch between entries with /provider, or switch only the model under the current provider with /model. The CLI also accepts one-shot overrides:

atomcode --provider deepseek --model deepseek-reasoner

Vision preprocessor

When the active provider's model can't read images (text-only models like DeepSeek-V3 / Kimi) and the user attaches an image, AtomCode doesn't refuse — it forwards the image to a separate "vision preprocessor" provider for OCR + description, then splices the resulting text into the user message before sending to the main model.

To enable: name an image-capable provider key as vision_preprocessor_provider in the config:

default_provider = "deepseek"
vision_preprocessor_provider = "qwen-vl"

[providers.deepseek]
type = "openai"
api_key = "sk-..."
model = "deepseek-chat"
base_url = "https://api.deepseek.com/v1"

[providers.qwen-vl]
type = "openai"
api_key = "sk-..."
model = "Qwen/Qwen3-VL-32B-Instruct"
base_url = "https://api.siliconflow.cn/v1"

qwen-vl must be an existing key under [providers.*], and its model must support vision input (common ones: Qwen3-VL-* / GLM-4V-* / claude-3+ / gpt-4o / gemini-*).
When the active provider can already see images, the preprocessor is skipped — the raw image bytes are sent directly.
The /login flow auto-picks a VL/OCR model from the granted model list and writes this field for you (you can override afterwards).
VL calls use an idle timeout: no total cap as long as the stream keeps producing chunks; the request times out after 30 seconds with no activity. On failure the main model still receives a "vision recognition failed" notice rather than a silent drop.

For usage-level details see Basic Usage · Image attachments / screenshots.

Three ways to edit the config

Hand-edit — open ~/.atomcode/config.toml in your favourite editor.
/config in the TUI — atomcode opens the config in your default editor.
/provider in the TUI — interactively add / edit / remove providers; changes are written back to disk.

Next steps

Login Methods — skip manual key management with AtomGit OAuth.
Basic Usage — see how CLI flags can override config for one run.