|
| 1 | +# Configuration |
| 2 | + |
| 3 | +agent6 is **secure by default**: every field has a default (security-sensitive |
| 4 | +ones default to the safe value), so you only set what you want to change. This |
| 5 | +is the field reference; for the security model behind the `[sandbox]` and `[git]` |
| 6 | +fields see **[SECURITY.md](SECURITY.md)**. |
| 7 | + |
| 8 | +## Where config lives (layered, lowest precedence first) |
| 9 | + |
| 10 | +| Layer | Path | Set with | |
| 11 | +|---|---|---| |
| 12 | +| built-in defaults | — | (secure defaults, always present) | |
| 13 | +| global *(default location)* | `$XDG_CONFIG_HOME/agent6/config.toml` (default `~/.config/agent6/config.toml`; or set `AGENT6_CONFIG_HOME`) | `agent6 connect`, `agent6 model` | |
| 14 | +| per-repo *(override)* | `./.agent6/config.toml` | `agent6 init`, `agent6 config set --repo` | |
| 15 | +| explicit | `--config FILE` | `agent6 run --config FILE` | |
| 16 | + |
| 17 | +A per-repo config can be empty when the global config supplies a provider + |
| 18 | +model; the one thing a repo always needs is its `workflow.verify_command`. |
| 19 | + |
| 20 | +## Creating & inspecting |
| 21 | + |
| 22 | +- `agent6 connect` — add a provider + API key (stored `0600`), global. |
| 23 | +- `agent6 model <role> <provider> <model> [--thinking off|low|medium|high]`. |
| 24 | +- `agent6 init` — scaffold `.agent6/config.toml` + `AGENTS.md` in a repo. |
| 25 | +- `agent6 config show` — every effective value and which layer set it. |
| 26 | +- `agent6 config get|set|unset|add|remove <dotted.key> [value]` — edit one leaf |
| 27 | + (`--repo`, or `--machine FILE` for a machine `[config]` overlay). Every edit is |
| 28 | + re-validated and rolled back if it would produce an invalid config. |
| 29 | +- `agent6 config fill [--repo]` — materialize every resolved value into one file. |
| 30 | +- `agent6 check` — validate config + sandbox + provider keys without running. |
| 31 | + |
| 32 | +--- |
| 33 | + |
| 34 | +## `[agent6]` |
| 35 | + |
| 36 | +| Field | Default | Meaning | |
| 37 | +|---|---|---| |
| 38 | +| `config_version` | `1` | Config schema version (must be `1`). | |
| 39 | +| `workspace_subdir` | `".agent6"` | In-repo directory for config + run state (`config.toml`, `runs/`, `machines/`, `memories/`). **Global-config only** (a repo can't rename the directory it lives in); a bare name — no slashes, `..`, or absolute paths. | |
| 40 | + |
| 41 | +## `[providers.<name>]` |
| 42 | + |
| 43 | +One backend per block; `<name>` is yours to pick and is referenced from |
| 44 | +`[models.<role>]`. At least one provider is required. |
| 45 | + |
| 46 | +| Field | Default | `kind` | Meaning | |
| 47 | +|---|---|---|---| |
| 48 | +| `kind` | *(required)* | — | `"anthropic"` (Anthropic Messages) or `"openai"` (any OpenAI Chat-Completions-compatible endpoint: OpenAI, OpenRouter, Ollama, vLLM, LM Studio, llama.cpp). | |
| 49 | +| `api_key_env` | none | both | Env var holding the API key. Omit to use the key stored by `agent6 connect`, or for unauthenticated local endpoints. The env var (when set) takes precedence. | |
| 50 | +| `http_timeout_s` | `600.0` | both | Per-HTTP-call timeout (connect + read), seconds. Lower it to fail fast on a stuck endpoint. | |
| 51 | +| `prompt_caching` | `true` | anthropic | Enable Anthropic prompt caching. | |
| 52 | +| `base_url` | `https://api.openai.com/v1` | openai | Endpoint base URL (e.g. `https://openrouter.ai/api/v1`, `http://localhost:11434/v1`). | |
| 53 | +| `extra_headers` | `{}` | openai | Extra HTTP headers sent on every request (e.g. OpenRouter's `HTTP-Referer` / `X-Title`). | |
| 54 | + |
| 55 | +Each endpoint gets its own block, so OpenAI and OpenRouter run side-by-side |
| 56 | +under different `<name>`s. |
| 57 | + |
| 58 | +## `[models.<role>]` |
| 59 | + |
| 60 | +Role routing. Three roles, all optional: **`worker`** drives `agent6 run` / |
| 61 | +`resume` (its model's pricing also drives the USD→token budget conversion); |
| 62 | +**`planner`** drives `agent6 plan`; **`reviewer`** drives `agent6 review` + the |
| 63 | +in-loop critic. `planner` and `reviewer` fall back to `worker` when unset. Any |
| 64 | +provider may serve any role (cross-vendor mixes are fine). |
| 65 | + |
| 66 | +| Field | Default | Meaning | |
| 67 | +|---|---|---| |
| 68 | +| `provider` | *(required)* | A `[providers.*]` name. | |
| 69 | +| `model` | *(required)* | Model id at that provider. | |
| 70 | +| `temperature` | `0.0` | Sampling temperature pinned per call (`0.0`–`2.0`). `0.0` keeps the tool-use loop stable; some open-weights models degenerate at high temperature. | |
| 71 | +| `thinking` | none | Reasoning effort: `off` / `low` / `medium` / `high`. OpenAI-compatible reasoning models get a reasoning-effort knob; Anthropic maps it onto an extended-thinking budget (low/medium/high ≈ 4k/8k/16k tokens). Non-reasoning models ignore it. | |
| 72 | + |
| 73 | +## `[sandbox]` |
| 74 | + |
| 75 | +The security boundary. Profiles and the network model are specified in |
| 76 | +**[SECURITY.md](SECURITY.md)** (§3 profiles, §1b/§8 network); this is a summary. |
| 77 | + |
| 78 | +| Field | Default | Meaning | |
| 79 | +|---|---|---| |
| 80 | +| `profile` | `"auto"` | `auto` / `strict` / `hardened` → resolves to an effective `strict` / `hardened` / `none` (SECURITY §3). | |
| 81 | +| `agent_network` | `"providers"` | The agent's own egress: `providers` / `local` / `open` (SECURITY §1b). | |
| 82 | +| `tool_network` | `"block"` | Jailed-command egress: `block` / `only_explicit_states` / `allow` (SECURITY §8). | |
| 83 | +| `allow_urls` | `[]` | Extra agent egress hosts under `agent_network = "providers"` (`host`, `host:port`, or URL). Edit with `agent6 config add/remove sandbox.allow_urls <host>`. | |
| 84 | +| `run_commands` | `"ask"` | Whether the LLM gets `run_command`: `yes` / `no` / `ask`. | |
| 85 | +| `protect_git` | `true` | Re-bind `.git/` read-only in every jail. | |
| 86 | +| `protect_agent6` | `true` | Re-bind the `.agent6/` directory (config + run state) read-only in every jail. | |
| 87 | + |
| 88 | +## `[git]` |
| 89 | + |
| 90 | +| Field | Default | Meaning | |
| 91 | +|---|---|---| |
| 92 | +| `require_clean_worktree` | `true` | Refuse to start on a dirty worktree. | |
| 93 | +| `auto_stash` | `false` | Stash before, restore after the run. | |
| 94 | +| `branch_per_run` | `true` | Cut a fresh `agent6/<slug>` branch off HEAD (else stay on the current branch and remember the starting sha). | |
| 95 | +| `commit_strategy` | `"per_step"` | End-of-run finalization: `per_step` (keep N commits) / `squash` (one combined commit) / `stage` (leave staged) / `none` (leave unstaged). All strategies commit per-step *during* the run. | |
| 96 | +| `allow_push` / `allow_force` / `allow_history_rewrite` | `false` | Reserved. `git_ops.py` refuses push / `--force` / history rewrite / `reset --hard` **unconditionally** regardless of these (SECURITY §5). | |
| 97 | + |
| 98 | +### `[git.commit]` |
| 99 | + |
| 100 | +| Field | Default | Meaning | |
| 101 | +|---|---|---| |
| 102 | +| `name` / `email` | none | Override the commit identity (else use the project's `git config`). `agent6 run` refuses to start with no resolvable identity. | |
| 103 | +| `coauthor` | none | Append a `Co-authored-by:` trailer, e.g. `"Alice <alice@example.com>"`. | |
| 104 | + |
| 105 | +## `[workflow]` |
| 106 | + |
| 107 | +| Field | Default | Meaning | |
| 108 | +|---|---|---| |
| 109 | +| `verify_command` | `[]` | argv defining "a step succeeded". **Required for `agent6 run`** (checked at run time); `plan` / `review` don't need it. | |
| 110 | +| `verify_timeout_s` | `600.0` | Per-call timeout for `verify_command` / `metric.command`. | |
| 111 | +| `critic` | `"off"` | In-loop critic (runs the `reviewer` model): `off` / `on_verify_fail` / `before_finish` / `periodic`. | |
| 112 | +| `critic_period` | `10` | Iterations between critiques when `critic = "periodic"`. | |
| 113 | +| `revise_prompt` | `"off"` | One-shot task-prompt revision before the loop: `off` / `auto` / `interactive`. | |
| 114 | +| `compact_drop_at_chars` | `256000` | Tier-1 compaction: replace oldest tool-results with a placeholder. | |
| 115 | +| `compact_summarise_at_chars` | `768000` | Tier-2 compaction: summarise elided history + restart (the task DAG survives). | |
| 116 | +| `context_summary_max_tokens` | `2048` | Cap on the tier-2 summary. | |
| 117 | + |
| 118 | +### `[workflow.metric]` (optional) |
| 119 | + |
| 120 | +A continuous score for tasks with a measurable goal. `command` runs in the jail |
| 121 | +like `verify_command`; `pattern`'s first capture group is parsed as a number. |
| 122 | + |
| 123 | +| Field | Default | Meaning | |
| 124 | +|---|---|---| |
| 125 | +| `command` | *(required)* | argv to run for the metric. | |
| 126 | +| `pattern` | *(required)* | Regex; first capture group = the numeric metric. | |
| 127 | +| `goal` | *(required)* | `"minimize"` or `"maximize"`. | |
| 128 | + |
| 129 | +## `[budget]` |
| 130 | + |
| 131 | +Hard stops; on hit the run aborts (exit 3) and is resumable (raise the limit and |
| 132 | +`agent6 resume <run-id>`). |
| 133 | + |
| 134 | +| Field | Default | Meaning | |
| 135 | +|---|---|---| |
| 136 | +| `max_input_tokens` | `2000000` | Input-token ceiling. | |
| 137 | +| `max_output_tokens` | `200000` | Output-token ceiling. | |
| 138 | +| `max_usd` | `0.0` (off) | Optional USD ceiling; converted to token caps using the worker model's pricing at load. | |
| 139 | + |
| 140 | +Override per-run from the CLI without editing config: `agent6 run --max-usd 5`, |
| 141 | +`--max-input-tokens`, `--max-output-tokens` (on `run`, `plan`, `resume`). |
| 142 | + |
| 143 | +## `[notify]` (optional) |
| 144 | + |
| 145 | +Runs an operator-controlled argv after `agent6 run` / `resume` (success or |
| 146 | +failure), **outside the jail** as your user, with `AGENT6_RUN_ID`, |
| 147 | +`AGENT6_RUN_DIR`, `AGENT6_RUN_OK` (`1`/`0`), `AGENT6_RUN_REASON` set. |
| 148 | + |
| 149 | +| Field | Default | Meaning | |
| 150 | +|---|---|---| |
| 151 | +| `on_complete` | `[]` | argv to run (empty = disabled). | |
| 152 | +| `timeout_s` | `30.0` | Hook timeout. | |
| 153 | + |
| 154 | +## `[mcp]` + `[[mcp.servers]]` (optional) |
| 155 | + |
| 156 | +Spawn Model Context Protocol servers at run start; their tools appear to the LLM |
| 157 | +as `mcp__<name>__<tool>`. Each server runs **as your user, outside the jail** |
| 158 | +(the `command` is operator-controlled, never LLM-influenced); the LLM *can* |
| 159 | +influence the arguments it passes, so audit each server like a `run_command` |
| 160 | +allow-list. |
| 161 | + |
| 162 | +| Field | Default | Meaning | |
| 163 | +|---|---|---| |
| 164 | +| `mcp.enabled` | `false` | Master switch; `false` means zero `mcp__*` tools. | |
| 165 | +| `servers[].name` | *(required)* | Tool prefix (`mcp__<name>__<tool>`). | |
| 166 | +| `servers[].command` | *(required)* | argv for the stdio JSON-RPC server. | |
| 167 | +| `servers[].enabled` | `true` | Per-server toggle. | |
| 168 | +| `servers[].startup_timeout_s` | `10.0` | `initialize` + `tools/list` handshake budget. | |
| 169 | +| `servers[].call_timeout_s` | `60.0` | Per `tools/call` timeout. | |
| 170 | + |
| 171 | +--- |
| 172 | + |
| 173 | +## Environment variables |
| 174 | + |
| 175 | +| Variable | Effect | |
| 176 | +|---|---| |
| 177 | +| `AGENT6_CONFIG_HOME` | Override the global config directory (default `$XDG_CONFIG_HOME/agent6`). | |
| 178 | +| `AGENT6_CACHE_HOME` | Override the cache directory (model-list cache, etc.). | |
| 179 | +| `AGENT6_JAIL_BIN` | Path to a specific `agent6-jail` binary (else the bundled one). | |
| 180 | +| `AGENT6_ALLOW_ROOT` | `1` permits running as root (same as `--allow-root`). | |
| 181 | + |
| 182 | +A provider's `api_key_env` (default `ANTHROPIC_API_KEY` etc.) supplies its key. |
| 183 | +A few additional `AGENT6_*` toggles exist for testing/advanced use; see the |
| 184 | +source if you need them. |
0 commit comments