olivier/claude-failover
1
0
Fork 0
Code Issues Pull requests 3 Projects Releases Packages Wiki Activity Actions
claude-failover/docs/configuration.md

2.5 KiB
Raw Blame History

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).