Configure Coddy

Configure Coddy

Use this skill when the user asks Coddy to configure itself. That includes explicit requests ("change the model", "set max turns to 40", "turn off auto discovery") and implied ones ("install a browser MCP", "add the pdf skill", "undo yesterday's config change"). Do not start configuring when the user has not asked for it.

Staged editing lifecycle

Configuration edits never apply immediately. The flow is always:

1. Inspect with config_get on the narrowest relevant path. Do not reconstruct unrelated config.
2. Stage edits with config_set. Nothing on disk changes; commands accumulate for this session.
3. Review with config_changes and summarize the pending commands to the user in plain language.
4. Ask the user to save. In any language, e.g. "I staged these changes: ... Save them?". Wait for a clear agreement ("да, сохраняй", "yes, save it", "go ahead").
5. Commit with config_commit only after that agreement. The commit validates the batch, snapshots the previous file, writes atomically, and hot-reloads the running session - new skills, rules and tools become usable in the same turn, no restart needed. MCP servers are not part of config.yaml (see MCP servers below).
6. If the user declines or changes their mind, drop the staged commands with config_revert (optionally scoped to one path).

config_commit also goes through Coddy's permission gate: it prompts even in accept_edits mode (a config commit can start MCP processes through mcp.project_trust and change the permission policy itself), and the dialog lists the staged commands with secrets redacted. Never weaken the permission policy merely to avoid that prompt, and never call config_commit before the user agreed to save.

Command syntax (uci-like)

config_set takes an array of commands shaped like OpenWrt's uci CLI:

Paths are dotted: agent.max_turns walks mappings, skills.dirs.0 indexes a list, providers[name=openrouter].api_base selects a named list entry. Unknown schema paths and values that make the config invalid are rejected at staging time, before anything is written.

config_get redacts credentials, proxy URLs and header values as <redacted>; a proxy set to inherit or none is shown as it is, since it names a route rather than a credential. Never write a returned <redacted> placeholder back into the config. Prefer ${ENV_VAR} references for secrets.

Rolling back a committed config

Every config_commit snapshots the previous file to config.yaml.prev next to the active config. When the user asks to return to the previous configuration, use config_rollback - but first warn them: the rollback replaces the current file with the snapshot, so anything committed after that snapshot disappears from the active config (the replaced file swaps into the snapshot slot, so one more rollback undoes it). Get explicit confirmation, then call the tool; it hot-reloads the runtime like a commit does. Do not confuse this with config.yaml.bak, which the loader refreshes to the current content on every successful start.

Configuration areas

The active YAML file covers these areas (full field tables: coddy_docs_read with page reference/config, or a section such as reference/config#providers, read from the documentation built into this binary; the same page is public at https://coddy.dev/docs/reference/config):

• providers - LLM backends: name, wire type (openai, anthropic, neuraldeep, codex, devin), base URL, API key or key command, per-provider proxy (the route of every request of the row, sign-in and usage reads included: inherit, the default, follows HTTPS_PROXY/HTTP_PROXY/NO_PROXY of the Coddy process, none connects directly past them, or an http, https, socks5 or socks5h URL; stage set providers.N.proxy=none for a provider the machine's proxy breaks), optional timeout_ms request bound, optional usage_limits_panel (default true; false hides the row's account usage panel on every surface and stops the usage reads behind it, meaningful for neuraldeep, codex and devin rows). neuraldeep, codex and devin support browser sign-in instead of a pasted key (coddy providers login <name> in a terminal; for neuraldeep and codex also the Sign In button on the provider row in Settings); the credential lands under $CODDY_HOME/providers/<name>/, never in config.yaml. For neuraldeep and devin an explicit api_key wins over a stored login; a codex row reads no api_key, api_key_command or NAME_API_KEY at all. Several rows may share a type as separate profiles (codex and codex-work, neuraldeep and nd-tech), each signed in on its own; coddy providers login codex-work --type codex creates a row config.yaml does not list yet. The Codex CLI and Devin CLI logins serve one row only - the only row of the type, or the row named codex / devin among several - so every other row needs its own login. The terminal logins (not the Settings button) also add the provider row, the models the account can use, and an agent.model when it is empty, unless --no-config is given; nothing already in the file is rewritten. For neuraldeep, api_base selects the deployment - https://api.neuraldeep.ru/v1 (Russia, used when empty) or https://api.neuraldeep.tech/v1 (the international mirror); any other value falls back to the first, and the choice also decides which hub signs the user in, so set it before login (coddy providers login neuraldeep --api-base <url>, which also moves an existing row to that endpoint). codex ignores api_base entirely. devin reaches a Devin (Cognition) account: coddy providers login devin signs in through the browser (--devin-cli reuses the login devin auth login holds instead), it ignores api_base, and its models are one entry per family whose reasoning_levels are the family's variants (devin/claude-opus-5 at high is sent as claude-opus-5-high), so keep the levels the login wrote rather than detecting them from the id; see https://coddy.dev/docs/features/devin;
• models - logical model entries (provider/model), token limits, reasoning options, and stream (set it to false when a backend or proxy cannot serve SSE: Coddy then sends one blocking request and shows the whole answer at once, which also means Stop during that call loses the answer; codex models reject it). The default model is agent.model (set agent.model=<provider/model>, one of the models entries): calls that name no model use it (coddy -p, coddy acp, API requests without a model selector) and report "no model configured" while it is empty, whereas the interactive surfaces (web UI, console, Telegram bot) pick a model per session. reasoning_levels has three states: key absent auto-detects the levels from the model id (the default), an explicit [] hides the reasoning selector, and a non-empty list offers exactly those levels; delete models.N.reasoning_levels returns an entry to auto-detection, set models.N.reasoning_levels=[] opts out. allow_reasoning_off defaults to false and exposes off only when the operator has verified that exact provider/model deployment honours Coddy's provider-specific disable-reasoning request;
• agent - ReAct loop model, max turns, queue_mode (steer at the next step or after_turn as a separate prompt; unset asks on first use), LLM retry and pacing (llm_retry_max: extra attempts shared by transport retries and consecutive empty-answer or first-token recoveries until tool progress or a new follow-up; 0 disables these retries, not the separately configured loop guard, Stop hooks, fallback models or quota-reset wait, llm_retry_base_ms, llm_min_interval_ms, llm_first_token_timeout_ms for the wait before the first token, llm_stream_idle_timeout_ms for a streamed answer that goes silent mid-way), loop protection, and the opt-in wait for a hit usage limit (wait_for_limit_reset, off by default, bounded by wait_for_limit_reset_max_ms, four hours);
• prompts - system prompt template overrides (agent_prompt, plan_prompt, ask_prompt files inside dir);
• instructions - extra instruction files appended after the AGENTS.md and DESIGN.md documents, in the order listed; empty by default. The documents themselves are never configured and cannot be turned off: the agent home's pair (${CODDY_HOME}/AGENTS.md, ${CODDY_HOME}/DESIGN.md), then the workspace's, then the nested pair of every folder on the way down to a file the agent works with, which arrives with the tool result or the message that first reaches that file. ${CODDY_HOME}, ${CWD} and ~ expand, an absolute entry is read as it stands; an entry naming a document already in the prompt is skipped, each file reaching the model once;
• skills - discovery dirs, project_trust (whether the project's .coddy/marketplaces.json takes effect: ask until an entry is approved, allow, deny), auto_discovery for the model-driven load_skill tool;
• rules - rule folders only: auto_discover reads one project folder, the first of .coddy/rules, the shared .agents/rules, .cursor/rules, .claude/rules and .codex/rules that holds a rule file, plus the operator's own ${CODDY_HOME}/rules, which applies in every workspace; systems narrows that to some of user, coddy, agents-dir, cursor, claude, codex, and a project folder it leaves out drops out of the chain. Neither key turns off the AGENTS.md and DESIGN.md documents, nested ones included; agents is still accepted in systems and changes nothing, but a list holding only agents still reads no rule folder;
• mcp - trust policy for project-local .coddy/mcp.json declarations (project_trust) and how long an MCP server no session holds keeps running before it is stopped (idle_timeout_seconds, 300 by default, 0 stops it at once; the servers are shared - one process per global declaration for the whole Coddy process, one per workspace for a project server - and the global ones that coddy serve, the console and coddy acp start stay up regardless). To keep project servers up for an hour after their last session, stage set mcp.idle_timeout_seconds=3600;
• tools - permission mode, command allowlist, background execution, output limits, SSH timeouts, tools.preview_server (the preview_server tool that serves a project directory on a free port for the operator's browser: enable, the bind host - 127.0.0.1 by default, and anything that is not loopback exposes the served files, so confirm it before you stage set tools.preview_server.host=0.0.0.0 - and public_host, the host written into the address handed out when the browser is on another machine; both are bare hosts, a port is a configuration error because the port is always a free one), and tools.websearch: the search engines the websearch tool asks in merge order (engines, brave then bing by default; ddg and google exist but are not asked by default because from a server one answers an anti-bot page and the other renders its results in the browser; searxng needs searxng_url), the per-engine and total budgets (engine_timeout_seconds, total_timeout_seconds), max_concurrent_engines, snippet_chars, cache_ttl_seconds (negative turns caching off), searxng_url for the operator's own instance (its settings.yml must list json under search.formats) and brave_api_key for the official Brave Search API. Prefer the BRAVE_API_KEY environment variable (or ${CODDY_HOME}/.env) to staging the key: an empty brave_api_key reads it, and a key never pasted into a staged command never passes through the model. An unknown engine name is a configuration error, and so is searxng without an address. To point search at a self-hosted aggregator, stage set tools.websearch.searxng_url=http://localhost:8080 and set tools.websearch.engines=["searxng","brave"]. tools.http_request.allowlist names the destinations the http_request tool reaches without a permission prompt: a host (api.github.com), a subdomain wildcard (*.example.com), either with an optional port, an origin (http://localhost:8080) or an address prefix (https://api.example.com/v1/); "*" allows everything. An entry also covers uploads and an unchecked certificate for that destination, a proxy needs an entry of its own, and an entry that cannot match (a path without a scheme, credentials, a wildcard in the middle) is a configuration error. Widening it removes a prompt the operator relies on, so confirm the exact entry before you stage add_list tools.http_request.allowlist=api.github.com. tools.http_request.default_headers is a map of headers every http_request call sends unless the call names the header itself (the call's value wins, and an empty value leaves the header out): stage one header with set tools.http_request.default_headers.User-Agent=Mozilla/5.0 (X11; Linux x86_64) Chrome/131.0.0.0 and drop it with delete tools.http_request.default_headers.User-Agent. A name is letters, digits, - and _, starting with a letter; Host, Content-Type, Content-Length, Transfer-Encoding, the hop-by-hop headers (Connection, Upgrade, ...) and Proxy-Authorization are refused, and webfetch and the model providers never send these headers. They reach every destination the tool calls, so never stage a credential (Authorization, Cookie, an API key) there unless the operator asked for exactly that. config_get shows you the names of the configured headers and never their values, so change them one header at a time: a value staged back as <redacted> is refused;
• subagents - child agents the model delegates to with spawn_agent: definition directories (dirs), the trust policy for definitions found inside the workspace (project_trust: ask refuses to spawn a project file until it is approved on the machine running coddy, with coddy agents trust <name> there, or POST /coddy/subagents/{name}/trust with the session workspace as cwd (the web UI's Settings → Subagents lists the definitions but approves none); from a remote console prefer the POST route or stage set subagents.project_trust=allow; allow trusts them, deny never reads them), the process-wide pool size (max_concurrent), nesting (max_depth), the default run timeout and the child ReAct cap. To let a trusted checkout's definitions run without approvals, stage set subagents.project_trust=allow; to shrink the pool, set subagents.max_concurrent=2;
• hooks - operator commands run at lifecycle points of a session (before and after a tool call: deny it, approve it past the permission prompt, rewrite its arguments, add context): the definition files (files, Claude Code's JSON shape, ~/.coddy/hooks.json plus the workspace's .coddy/hooks.json and .claude/settings*.json), the trust policy for files found inside the workspace (project_trust: ask lists them but runs nothing until the file is approved on the machine running coddy with coddy hooks trust <file> there or POST /coddy/hooks/trust; allow runs them like the operator's own file; deny never reads them), the per-hook default timeout (default_timeout_seconds), the Stop-hook loop cap (stop_loop_limit) and the output cap (max_output_chars). To let a trusted checkout's hooks run without approvals, stage set hooks.project_trust=allow; to switch hooks off, set hooks.enable=false;
• logger - root level, per-component overrides (levels, a list of {component, level} entries where a dotted name such as gateway.telegram raises or lowers one subsystem and a parent name covers what is nested under it), outputs, format, rotation;
• sessions - session bundle storage;
• compaction - context compaction: auto_enable for the threshold trigger, the threshold, the kept turns, the summarizer model and the fallback_models tried when it fails;
• supervisor - the session goal and its supervisor (/goal [-m|--model <id>] [-r|--reasoning <level>] <objective> sets a goal and starts work on it; the section is optional, supervisor: {} and no section at all mean the defaults; https://coddy.dev/docs/features/session-supervisor): model (the model that checks every goal turn, best of another family than the worker; empty uses the session model; /goal --model overrides it for one goal), verify (a read-only subagent confirms a met goal against the files, default true), max_continuations (automatic turns per goal, default 10, then one wrap-up turn), token_budget (per goal, 0 = no cap), the watchdog bounds stall_seconds (300), max_nudges (2) and loop_repeat (3), and enable (check ordinary turns against the latest request even without a goal);
• memory - the long-term memory subagent (binaries built with the memory tag), a child run every user turn starts in the task pool: its model and the fallback_models tried when that one fails before answering, wait_seconds (how long a turn waits for its report before the first model call, 0 never waits), timeout_seconds (the run's hard limit), keep_runs (finished runs kept per session in the Tasks panel, 0 keeps all), max_note_chars (longest body one saved note may have, in characters, default 900, 0 removes the cap), additional_prompt (the operator's own instructions for the memory subagent, a section of its prompt the main agent never sees) and additional_prompt_max_chars (cut that text at so many characters, 0 keeps it whole);
• httpserver - OpenAI-compatible HTTP API: enable (omitted means true), bind address (empty means 127.0.0.1), auth token, login (the optional web UI sign-in: enable, user, password_hash, session_ttl_hours - write it with coddy serve set-password, never by hand, and never a plaintext password), cors (enable, exact allowed_origins, and allow_loopback - set httpserver.cors.allow_loopback=true - for a web UI served by a laptop's own coddy serve on any loopback address and port; allow_loopback and "*" are only as safe as the token or the sign-in form, so set one of those first), UI (tag http), and remotes, the servers and relays the web UI's environment menu offers and coddy --remote <name> resolves: name, url and an optional token (a relay's client token or a server's auth token, best as a ${ENV} reference; every browser that reads this config receives it). To offer a relay, stage set httpserver.remotes[name=office]={"url":"http://relay.lan:12346","token":"${CODDY_RELAY_TOKEN}"}; the relay also needs to admit this page's origin through its swarm.cors - exactly in allowed_origins, or with allow_loopback: true for a page on a loopback address;
• swarm - relay that nodes register into and that chains into other relays: enable, name (empty: the host name), bind address, client and pairing tokens, cors (the origins of pages served elsewhere allowed to call the relay: exact allowed_origins, and allow_loopback for a laptop's web UI on any loopback address and port), TLS, upstreams, and the join list this process registers itself into (tag swarm; join is honoured whether or not this process relays; an entry without name claims the host name). A relay's own page edits this block in Settings, and a save rebuilds the relay;
• scheduler - cron scheduler: enable, project_trust (ask, allow or deny for the project jobs a repository carries in <workspace>/.coddy/scheduler; user jobs live in ${CODDY_HOME}/scheduler, and neither folder is configurable - the old dir key is moved out on load), max_queue (runs in flight across all jobs), timeout (one run's wall-clock limit) and retain_sessions (finished runs kept per job, with their transcripts). A run is a background agent task under the job's own session; a job file may also name a subagent definition (agent) and a permission_mode (tag scheduler);
• gateways - messenger bots: Telegram (gateways.telegram.enable, token, access control, and mini_app - url, the public https address of the web UI (behind a TLS proxy), which the bot's menu button and /app open as its Telegram Mini App, and menu_button (default true; false leaves the button to @BotFather); the bot advertises the web UI only when it asks for a sign-in or a token, or httpserver.allow_insecure is true) and the Pachca integration bot (gateways.pachca.enable, token or PACHCA_BOT_TOKEN, poll_interval_seconds 1 to 60, the same admins / default_access / default_isolation / user_groups / chats as Telegram), each with a proxy read like a provider's (inherit follows HTTPS_PROXY, none connects directly, or a URL) (tag gateway, or gateway.telegram / gateway.pachca for one bot). The Pachca bot also needs "Save events history" turned on in its settings in Pachca; see https://coddy.dev/docs/surfaces/pachca.