manage the server

the orcr server is the single long-lived process and the single writer. it owns the store, the admission queue, GC, loop scheduling, reconciliation, and the event stream, and it exposes everything over a Unix socket. you rarely start it by hand, since any CLI or SDK call auto-starts it, but these verbs let you operate it directly.

orcr server start | stop | status | logs | enable | disable

enable and disable are covered in run orcr as a service.

start: idempotent

if a healthy server already answers the handshake, start exits 0 (already_running in JSON). otherwise it starts the server under the single-instance lock and blocks until the readiness handshake succeeds. auto-start by other verbs is this same path.

orcr server start
orcr server start --foreground   # run in the foreground (what the service unit uses)

auto-start and single-instance locking

any CLI or SDK call auto-starts the server first if it is not running. startup takes an exclusive lock file in ~/.orcr (flock), and the server refuses to open the store without it. two clients racing to auto-start do not spawn two servers: the loser of the start race waits for readiness instead. readiness is a handshake response carrying the pid, protocol version, and store path. the lock is released on process exit, including kill -9, so a crashed server does not wedge the next start. distinct errors separate the failure modes: server_unreachable (cannot connect), server_start_failed (spawn failed), herdr_unreachable (server fine, herdr not).

stop: a control-plane pause, not a kill switch

stop is a graceful control-plane stop. it stops accepting requests, closes subscriptions with server_stopping, persists queue, GC, and loop state, and releases the socket.

while the server is stopped: no loop fires (missed ones are skipped and logged on restart), no queue promotion, no GC (clocks are recomputed from persisted timestamps on restart), and no unmanaged discovery. because any CLI call auto-starts the server again, a stop followed by any other command brings it right back. that is expected: stop is not a switch that keeps it down.

status: the health probe

orcr server status
orcr server status --json

status reports the server version and protocol version, the socket and store paths, the herdr binary with its reachability, version, protocol, session socket path and running state, fleet counts, whether loop firing is enabled, the loop schedule and next fires, and reconciliation drift. the JSON shape:

{
  "version": "…", "protocol": 1,
  "socket": "/home/you/.orcr/orcr.sock",
  "store": "/home/you/.orcr/store.db",
  "herdr": { "bin": "…", "reachable": true, "version": "0.7.x", "protocol": 16,
             "socket": "/home/you/.orcr/herdr-orcr.sock",
             "session": "orcr", "session_running": true },
  "integrations": { "claude": { "orcr": true, "herdr": true }, "codex": { "orcr": true, "herdr": true } },
  "counts": { "live": 9, "queued": 2, "blocked": 1, "unmanaged": 1,
              "orphan_agent_panes": 0, "unmarked_panes": 0 },
  "loops_firing": true,
  "loops": [{ "name": "nightly", "status": "active", "next_fire_at": "…" }],
  "drift": { "lost": 0, "repaired": 0 }
}

what to read it for:

• integration state: integrations shows which providers have both layers installed. a missing layer is why agent run -a <p> would fail with integration_missing. see providers and integrations.
• counts: live/queued/blocked/unmanaged are the fleet at a glance. orphan_agent_panes and unmarked_panes are panes in the owned session that orcr reports but never touches (clean those up through herdr directly).
• drift: lost and repaired come from reconciliation, the periodic repair between what the store says and what herdr actually shows. see durability and recovery.

logs: the server's own log

orcr server logs
orcr server logs --tail 200
orcr server logs --follow

logs reads the server log at ~/.orcr/logs/server.log: startup, herdr connection events, reconciliation actions, GC decisions, and errors. --tail <n> and --follow work as everywhere else. this is the server's own log; an agent's transcript is orcr agent logs, and a loop run's output is orcr loop logs.

the socket and home safety

the socket is a Unix domain socket at ~/.orcr/orcr.sock, created with umask 077 and mode 0600. filesystem permissions are the only authentication: only processes running as your uid can open the socket, and there is no TCP port. the server refuses to start with unsafe_home unless ~/.orcr is owned by your uid and is not group- or world-writable. socket paths are validated against symlinks, and a stale socket is unlinked only while holding the instance lock and only if it is same-uid.

next

• run orcr as a service: start the server at login.
• configure orchestratr: the knobs the server reads.
• architecture: the single-writer design.
• durability and recovery: reconciliation and crash safety.