configure orchestratr

configuration lives in ~/.orcr/config.json (strict JSON). every key is optional and has a default, so most setups touch only a few knobs. this page covers the ones you reach for; the configuration reference documents every key.

precedence

values resolve in one order everywhere:

CLI flag  →  config.json  →  built-in default

a --gc or -a on the command line beats the config, which beats the shipped default.

the knobs you actually touch

// ~/.orcr/config.json: every key optional; defaults shown
{
  "concurrency": {
    "max": 25,                 // global ceiling (RAM protection)
    "claude": 10               // per-provider caps beneath it (any provider is a key)
  },
  "timings": {
    "idle_after": "5m",        // turn-complete + idle this long → parked
    "kill_after": "10m",       // parked this long → reaped
    "gc_tick": "30s",          // GC engine cadence
    "attach_lease_ttl": "30s", // heartbeat expiry for attach leases
    "run_term_grace": "10s"    // loop-run stop/timeout TERM→KILL grace
  },
  "integrations": {
    "claude": { "idle_stable_ms": 1200 }   // per-provider completion tuning
  }
}

concurrency caps

concurrency.max (default 25) is the global ceiling on live agents, RAM protection because heavy TUIs at 100x will take a machine down. per-provider caps sit beneath it (any provider name is a key); promotion from the queue needs a free slot in both the global cap and the provider's cap. lower max on a small machine; raise a provider's cap if that provider is your bottleneck and you have the RAM. see queue and concurrency.

GC timings

the timings.* block collects every duration knob in one place. the three you are most likely to change govern parking and reaping under --gc auto: an agent idle past idle_after is parked, and a parked agent past kill_after is reaped. raise them for agents you keep coming back to; the behavior itself is in agent lifecycle and GC.

completion tuning

per-provider completion tuning is integration logic, with defaults shipped inside each integration. override any of them per provider under integrations.<provider>.*:

fast_turn_grace_ms · idle_stable_ms · transcript_settle_ms
transcript_freshness_timeout_ms · shutdown_grace_ms

these decide when a turn counts as complete (working-after-delivery, stable idle, transcript settled). integrations is a known key, validated like the rest, not an unknown-key warning. change these only if a provider's turns are being marked complete too early or too late; see status model and completion.

provider defaults and herdr

{
  "defaults": {
    "agent": "claude",   // default provider when -a is omitted
    "model": "",         // empty = provider default
    "effort": ""
    // no default timeout: agents never time out unless --timeout is passed
  },
  "herdr": {
    "bin": "",           // empty = $ORCR_HERDR_BIN → $PATH
    "session": "orcr"    // the owned session; user sessions are never touched
  }
}

defaults.* is covered in choose providers and models. note there is no default timeout: an agent never times out unless you pass --timeout.

validation is strict

validation runs at server start and on reload:

• unknown keys warn and are ignored, with the nearest valid name suggested, so early configs stay forward- and backward-compatible instead of failing.
• known keys are validated strictly. durations require units and must be positive. concurrency.max must be at least 1. per-provider caps are clamped to max with a warning. herdr.session must be a valid session name.

a genuinely invalid config surfaces as environment_error (cause config_invalid).

environment overrides

• ORCR_HOME relocates the entire ~/.orcr tree (store, socket, lock, config, logs, data). use it for tests and sandboxes.
• ORCR_HERDR_BIN overrides herdr binary discovery.
• ORCR_HERDR_SESSION overrides herdr.session (empty falls back to config or default).

next

• configuration reference: every key, default, and constraint.
• manage the server: the process that reads this config.
• queue and concurrency: what the caps protect.
• choose providers and models: the defaults block.