configuration reference

orcr reads ~/.orcr/config.json (strict JSON, no comments in the real file). every key is optional; the defaults below apply when a key is absent. validation happens at server start and on reload.

// ~/.orcr/config.json: comments are illustrative; defaults shown
{
  "defaults": {
    "agent": "claude",        // default provider (used when -a is omitted)
    "providers": {
      "claude": { "model": "sonnet", "effort": "medium" },
      "codex": { "model": "gpt-5.6-luna", "effort": "high" }
    }
    // 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
  },
  "concurrency": {
    "max": 25,                // global ceiling (RAM protection)
    "claude": 10              // per-provider caps beneath it (any provider is a key)
  },
  "timings": {                // every duration knob in one place
    "idle_after": "5m",       // turn-complete + idle this long → parked
    "kill_after": "10m",      // parked this long → reaped
    "gc_tick": "30s",         // GC engine cadence
    "max_starting": "2m",     // stuck-start guard
    "attach_lease_ttl": "30s", // heartbeat expiry for attach leases
    "loop_tick": "1s",        // loop scheduler tick cadence
    "run_term_grace": "10s"   // loop-run stop/timeout TERM→KILL grace
  },
  "logs": { "max_bytes": 10485760, "max_files": 5 },   // server + loop-run logs
  "integrations": {           // per-provider completion-tuning overrides
    "claude": { "idle_stable_ms": 1200 }
  }
}

defaults

--model and --effort override the selected provider's entries. orcr resolves both values before enqueueing, passes both explicitly to the provider, and records the resolved pair on the agent.

model and effort availability is checked at agent run, after CLI/config resolution and before the agent is enqueued. invalid errors print the valid values and expose them as structured arrays.

there is no default timeout. an agent never times out unless --timeout is passed.

herdr

concurrency

promotion from the queue needs a free slot in both the global cap and the per-provider cap. see queue and concurrency.

timings

every value is a duration and must carry a unit (5m, 30s) and be positive.

see lifecycle and GC for idle_after/kill_after, and loops for the run grace.

logs

integrations

per-provider completion tuning. defaults ship inside each integration; any of the parameters below may be overridden per provider under integrations.<provider>.* (values in milliseconds). integrations is a known key, validated like the rest, not treated as an unknown-key warning.

see status and completion for how these parameters drive verified idle.

validation

at server start and on reload:

• unknown keys warn and are ignored, with the nearest valid name suggested. this keeps config forward- and backward-compatible for early users.
• 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, and herdr.session must be a valid session name.

an invalid known value surfaces as environment_error (cause: config_invalid).

precedence

CLI flag over config over built-in default. for example, -a codex on the command line overrides defaults.agent in config, which overrides the built-in claude.

environment overrides

the full environment contract, including the variables injected into agents and loop-run commands, is on the environment variables reference.