Config Setup

Configure octo

Your job is to turn "I need my agent to use model X" or "change setting Y" into a working configuration through octo's REST API. Not every user knows where settings live — briefly explain when needed.

Two categories of configuration

Agent Defaults                    Endpoints & Models
─────────────────                 ───────────────────
reasoning_effort                  provider selection
permission_mode                   API key
show_reasoning                    base URL (advanced)
coauthor                          model names
workspace_dir                     default / lite model

All of these live in ~/.octo/config.yml and are editable through the REST API on the running octo server at http://localhost:<port> (use curl via the terminal tool — do NOT use web_fetch, localhost is blocked by SSRF).

Reaching the server

The server listens on 127.0.0.1:8088 by default (the desktop app's built-in server uses the same port). Loopback requests need no access key.

A session running inside the server (Web UI, desktop, IM) has an Octo server: line in its Environment section. When it's there, use that address in place of 127.0.0.1:8088 in every command in this skill and skip the steps below.

1. Try the default first: curl -s http://127.0.0.1:8088/api/config. JSON back = you're connected; skip the rest of this section.
2. Connection refused? The server may be on a custom port:
   • Started as a daemon (octo serve -d): cat ~/.octo/serve.pid for the PID, then find its listen port — macOS/Linux: lsof -iTCP -sTCP:LISTEN -P -n -a -p <PID>; Windows (PowerShell): Get-NetTCPConnection -State Listen -OwningProcess <PID>.
   • A foreground octo serve writes no pid file — ask the user which port they started it on (it's also in the web UI's address bar).
3. No server running at all? Don't stop — fall back to editing ~/.octo/config.yml directly (it is the same file every API call below mutates). Read the file first, apply the smallest edit that matches the structure you see, then validate with octo doctor. Changes are picked up by new CLI sessions and by the server next time it starts.

Agent Defaults

These are global settings that govern how the Default Agent behaves. All are individual PUT endpoints returning 200 on success, 400 on invalid input.

Reasoning Effort

PUT /api/config/reasoning_effort
{"reasoning_effort": "off"|"low"|"medium"|"high"|"xhigh"|"max"}

Permission Mode

PUT /api/config/permission_mode
{"permission_mode": "interactive"|"auto"|"strict"}

Show Reasoning

PUT /api/config/show_reasoning
{"show_reasoning": true|false}

When enabled, the agent's thinking process is visible in the chat.

Coauthor

PUT /api/config/coauthor
{"coauthor": true|false}

When enabled, appends a Co-authored-by: octo-agent trailer to git commits.

Workspace Directory

PUT /api/config/workspace_dir
{"workspace_dir": "/absolute/path"|"auto"}

Sets the default working directory for new sessions. Use "auto" to let octo detect the project directory automatically. Only absolute paths are accepted (no ~ — expand it to the full path first).

Read Current Defaults

GET /api/config

Returns the full current config including all defaults. Use this to show the user their current settings before making changes.

Endpoints & Models

An "endpoint" groups a provider with its API key, then lists the models available through it. The two-level structure:

Endpoint "anthropic"                  Endpoint "relay-a"
  provider: anthropic                   provider: custom
  api_key: sk-ant-…                     api_key: sk-…
  models:                               models:
    - claude-sonnet-5                     - gpt-4o
    - claude-haiku-4-5                    - deepseek-flash

Two top-level composite ids pick across endpoints: default (e.g. anthropic::claude-sonnet-5) is what the agent uses for normal turns, and lite (e.g. anthropic::claude-haiku-4-5) is used for lightweight tasks (title generation, compaction summaries). An empty lite means those run on the primary model — nothing cheaper is inferred.

List Endpoints

GET /api/config/endpoints

Returns all configured endpoints with their models, including which is default/lite.

List Available Providers

GET /api/providers

Returns the built-in provider registry — each entry has a name, base_url, and models (suggested model names). Use this to help the user pick a provider.

Create an Endpoint

POST /api/config/endpoints
{
  "id": "my-relay",
  "name": "My Relay",
  "provider": "custom",
  "api_key": "sk-…",
  "base_url": "https://api.example.com",
  "protocol": "openai",
  "models": [{"model": "gpt-4o", "vision": false}]
}

Update an Endpoint

PATCH /api/config/endpoints/{id}
{
  "new_id": "new-name",     // rename (optional)
  "name": "New display",    // new display name (optional)
  "provider": "openai",     // change provider (optional)
  "api_key": "sk-…",        // update key (optional)
  "base_url": "https://…",  // change URL (optional)
  "protocol": "openai"      // change protocol (optional)
}

All fields are optional — only include what's changing. To rename, set new_id.

Delete an Endpoint

DELETE /api/config/endpoints/{id}

Returns 204. Destructive — deletes the endpoint and all its models. Confirm with the user before calling.

Add a Model to an Endpoint

POST /api/config/endpoints/{id}/models
{"model": "gpt-4o", "vision": true}

vision (optional, default false): whether this model supports image input.

Delete a Model from an Endpoint

DELETE /api/config/endpoints/{id}/models/{model}

The model name must be URL-encoded when it contains special characters — this matters for slash-style names like deepseek/deepseek-chat, which becomes deepseek%2Fdeepseek-chat in the path.

Set Default / Lite Model

POST /api/config/endpoints/{id}/default?model=gpt-4o
POST /api/config/endpoints/{id}/lite?model=claude-haiku
DELETE /api/config/endpoints/{id}/lite   // clear lite designation

The model is passed as a query parameter (?model=…), not in the request body. Omit ?model to use the endpoint's first model as a fallback.

Important: This changes the server-wide default that seeds new sessions. It does not switch the model of any session that is already running or already bound to a specific model. For those, see Switching the Current Session's Model.

Switching the Current Session's Model

A session is bound to the global default model only at creation time. Once it has a turn, it keeps that model until you explicitly switch it. This applies to Web, TUI, CLI one-shot, and IM sessions.

• Web UI: Click the model chip in the Composer status bar (the row showing the current model name, e.g. K3), then pick the desired model from the dropdown.
• IM (Weixin/Feishu/DingTalk/WeCom/Discord/Telegram): Send /model to list configured models and see the current one, then /model <endpoint>::<model> to bind the session to that endpoint's model, or /model default to make it follow the server-wide default again. You cannot switch while a turn is running.
• REST API:

PATCH /api/sessions/{id}/model
{"model_id": "Kimi::k3-256k"}

Use default as the model_id to unbind the session from a specific endpoint and make it follow the global default on subsequent turns. Unknown or bare model strings are treated as raw model names on the default sender.

Restart behavior: You do not need to restart octo serve after changing the global default or a session's model. Both take effect on the next turn. The only exception is a session that was already bound to a model before the change — it will not switch unless you use one of the methods above.