Skip to content

Commit 0b64bab

Browse files
committed
refactor: drop agent6.example.toml + the vestigial agent6.toml magic protect
The per-repo config has been `.agent6/config.toml` (created by `agent6 init`, inspected by `agent6 config show`, editable via `agent6 config set`) for a while; the root `agent6.toml` is a legacy name the loader never reads. So: - Replace agent6.example.toml with CONFIG.md — the same annotated field reference, as Markdown tables per section (and an env-vars section), linking SECURITY.md for the sandbox/git security model. More discoverable; nothing to copy-paste. - Remove the `agent6.toml` magic protect-path from the jail policy (it guarded a file agent6 never reads/creates). Update the describing comments in types.py, config.py, and jail/src/main.rs. - Replace the scattered "agent6.toml" references in error messages / help text / docstrings with "your config" / `.agent6/config.toml` (it was never the actual config filename). - README/pyproject/paths.py point at CONFIG.md instead of the example; the jail-smoke file-protect test uses a neutral sample filename. Security review note: `protect_agent6` no longer re-binds `<cwd>/agent6.toml` read-only. No regression — the actual config (`.agent6/config.toml`) stays protected via the `.agent6/` directory, which `protect_agent6` still covers; the removed path guarded a root file the loader never reads (only reachable via `--config`, which was never protected either). `agent6-jail` (main.rs) change is comment-only: no mount/landlock/seccomp/dev behavior changed. Full gate green.
1 parent a2e4b39 commit 0b64bab

19 files changed

Lines changed: 208 additions & 332 deletions

File tree

‎CONFIG.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
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.

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -191,9 +191,9 @@ breakdown, and the sandbox profiles.
191191
## Configuration
192192

193193
agent6 is **secure by default**: every field has a default, and
194-
security-sensitive ones default to the safe value. The full annotated
195-
reference is [agent6.example.toml](agent6.example.toml); the sandbox
196-
profiles and security knobs are explained in [SECURITY.md](SECURITY.md).
194+
security-sensitive ones default to the safe value. The full field
195+
reference is [CONFIG.md](CONFIG.md); the sandbox profiles and security
196+
model are explained in [SECURITY.md](SECURITY.md).
197197
Get started with `agent6 connect` + `agent6 model` (global) and
198198
`agent6 init` (per-repo). `agent6 config show` audits every effective
199199
value and where it came from; `agent6 check` validates without running.

0 commit comments

Comments
 (0)