# Configuration

Configuration is a single YAML file (`config.yaml`) read at startup.
`config.example.yaml` at the repository root is the annotated template —
copy and edit.

## Sections

### `accounts`

List of Anthropic accounts the daemon may rotate through.

| Field            | Type     | Description |
|------------------|----------|-------------|
| `name`           | string   | Short identifier used in logs and metrics. |
| `home`           | path     | Per-account home directory (houses the private `~/.claude` credentials). |
| `limits.hourly_msgs` | int  | Local soft cap on messages per hour. `0` disables. |
| `limits.weekly_msgs` | int  | Local soft cap per 7-day window. `0` disables. |
| `priority`       | int      | Lower numbers preferred when selecting a primary. |

### `pool`

Session pool layout.

- `dedicated` — long-lived sessions bound to a specific project path.
  Each entry has `name` (tmux session) and `project` (absolute path).
- `autonomous` — autoscaling pool for the inbox dispatcher.
  `prefix` + serial → session names; `min`/`max` bound the pool size.
- `shared_projects_dir` — canonical Claude Code `projects/` tree,
  symlinked from every account home (see
  `docs/session-switch-analysis.md`).

### `quota`

Failover thresholds.

- `poll_interval` — how often the quota-monitor samples usage.
- `window_5h_threshold` — fraction (0..1) of the 5h cap above which a
  swap is requested.
- `window_week_threshold` — same idea for the weekly cap.
- `reactivate_cooldown` — minimum time before a drained account is
  eligible again.

### `checkpoint`

- `dir` — where per-session snapshots are written.
- `interval` — time between snapshots.
- `keep` — retention per session (older files are pruned).

### `mcp_http`

HTTP control plane for the MCP gateway.

- `listen` — bind address (keep it loopback unless fronted by a reverse
  proxy).
- `bearer_token_env` — name of the env var from which to read the
  bearer token required on every request.
- `enable_trigger` — gate for mutating routes (`/trigger/*`).

## Secrets

The config file itself holds no secrets. Bearer tokens and account
credentials are read from the environment. In production deploy via a
systemd unit with a drop-in that sources `/run/secrets/claude-failover.env`
(populated by `secuops` / OVH KMS at boot).

## Reload

Config reload is not supported in the initial version. A SIGHUP handler
is planned — the account-switcher makes a clean live reload feasible
(drain, reconfigure, resume).