Configuration

Coderrr keeps its settings in ~/.coderrr/config.toml, created with owner-only permissions (mode 0600).

Interactive setup

coderrr config

Provider — pick one of five
API key — skipped for Ollama; leave blank to keep an existing key
Model — chosen from that provider's suggestions
Endpoint — asked for Ollama only, so you can point at a remote host

Inspect and clear

coderrr config show    # current settings, key masked
coderrr config clear   # delete the file and any keyring entries

config show prints a table:

──────────────────────── Configuration ────────────────────────
  Setting     Value
  provider    anthropic
  model       claude-sonnet-4-20250514
  endpoint    (default)
  api key     sk-ant...4Jx2
  max_iter    5
  verify      writes_only
  sandbox     auto

◇ File: /home/you/.coderrr/config.toml

How credentials resolve

Three sources, checked in this order. The first hit wins, so CI and one-off overrides never require touching stored state.

Order	Source	Notes
1	Environment variable	Always wins. Ideal for CI.
2	OS keyring	Used when the `keyring` extra is installed. A locked or misconfigured keyring is skipped rather than fatal.
3	`~/.coderrr/config.toml`	Fallback when the keyring is unavailable. Written mode 0600.

Environment variable	Provider
ANTHROPIC_API_KEY	Anthropic
OPENAI_API_KEY	OpenAI
GOOGLE_API_KEY	Google Gemini
OPENROUTER_API_KEY	OpenRouter
OLLAMA_API_KEY	Ollama (only needed for Ollama-hosted models)

config.toml

Every table is optional — omitted keys fall back to the defaults shown here. A malformed file is ignored rather than fatal, so a bad edit degrades to defaults instead of breaking the CLI.

[provider]
name     = "ollama"
model    = "gemma4:31b-cloud"
# endpoint is only meaningful for Ollama
endpoint = "http://localhost:11434/v1"

[agent]
max_iter       = 5      # retries per task after a failed verification
max_tool_turns = 50     # tool calls per attempt before giving up
max_tokens     = 8192
temperature    = 0.2
max_seconds    = 1800   # wall-clock ceiling for one task attempt
confirm_writes = false  # true prompts on every individual write

[verify]
mode        = "writes_only"  # always | writes_only | off
model       = ""             # empty reuses the main model; point at a cheap one
batch       = true
temperature = 0.3            # above zero so a false reject isn't repeatable

[sandbox]
tier    = "auto"             # auto | scratch | docker
network = false
timeout = 300                # seconds per command
image   = "python:3.12-slim" # docker tier only

[skills]
registry  = "https://raw.githubusercontent.com/Akash-nath29/coderrr-skills/main/registry.json"
ephemeral = true             # delete skills from disk after use

[mcp]
max_result_bytes = 65536     # cap on one tool result folded into context

# written by `coderrr mcp add`; hand-editable
[mcp.servers.figma]
transport     = "http"       # http | stdio
url           = "http://127.0.0.1:3845/mcp"
auth          = "auto"       # auto | none — OAuth when the server asks for it
required      = false        # true: a connect/login failure aborts the run
timeout       = 30.0         # seconds per request
allowed_tools = ["get_code"] # answered "always allow"
denied_tools  = []           # never bridged at all

[ui]
stream     = true
show_usage = true

[agent]

Key	Default	What it does
max_iter	5	How many times a single task is retried after it fails verification. 1–20.
max_tool_turns	50	Cap on tool-call turns within one task attempt, so a model that keeps calling tools cannot spin forever. 1–500.
max_tokens	8192	Output token ceiling per model call.
temperature	0.2	Sampling temperature for the agent itself.
max_seconds	1800	Wall-clock ceiling for one task attempt.
confirm_writes	false	Approval normally happens once, at the plan boundary. Set true to also be prompted on every individual write.

[verify]

After a write, a second model call checks that the change actually matches the task. writes_only runs that check on writes; always checks every tool result; off disables it.

Key	Default	What it does
mode	"writes_only"	always \| writes_only \| off
model	""	Empty reuses the main model. Pointing this at something cheap is usually the right call.
batch	true	Verify a group of writes in one call rather than one per write.
temperature	0.3	Deliberately above zero: at 0.0 a weak verifier's false rejection is deterministic, so the retry loop can never escape it.

[sandbox]

See Sandbox for what each tier actually isolates.

Key	Default	What it does
tier	"auto"	auto uses Docker when it is available and falls back to scratch. Pin it with scratch or docker.
network	false	Docker tier runs with --network=none unless this is true.
timeout	300	Seconds before a command is killed.
image	"python:3.12-slim"	Container image for the Docker tier.

[mcp]

One table per connected server, written by coderrr mcp add. Full detail — every key, the OAuth flow, and per-tool approval — is in MCP Servers.

Key	Default	What it does
mcp.max_result_bytes	65536	Cap on how much of one MCP tool result is folded into context. A server can return a whole design file.
servers.<name>.transport	"http"	`http` uses `url` and `headers`; `stdio` uses `command`, `args`, `env` and `cwd`
servers.<name>.auth	"auto"	`auto` attempts OAuth when the server answers 401; `none` never does
servers.<name>.required	false	true makes a connect or login failure abort the run instead of quietly shortening the tool list.
servers.<name>.allowed_tools	[]	Tools answered "always allow". denied_tools hides a tool entirely.
servers.<name>.enabled	true	Off keeps the configuration but stops using the server.

Tokens are not kept here

MCP OAuth tokens go to your OS keyring, falling back to ~/.coderrr/credentials.json at mode 0600 — never to config.toml, which is rewritten on save and meant to be committable. For a static token, use ${VAR} in a header and keep the value in your environment.

[skills] and [ui]

Key	Default	What it does
skills.registry	coderrr-skills	URL of a `registry.json` index. Point it at your own to use a different one.
skills.ephemeral	true	Delete fetched skills from disk after use.
ui.stream	true	Stream model output as it arrives.
ui.show_usage	true	Print token counts when a run finishes.

Per-run overrides

coderrr run "..." -m gpt-4o        # one-off model override
coderrr run "..." -d ../other-repo # different workspace root
coderrr run "..." --yes            # skip the approval prompt

--yes skips the prompt, not the plan

A spec is still written and still has to contain tasks before anything is executed. --yes waives your confirmation, not the requirement that a plan exist.