OpenRig explained: coordinate coding agents without losing the operator
OpenRig architecture: from a RigSpec to live agent seats
Trace declarations, daemon state, tmux sessions and runtime adapters
What you will learn
- Compile the declared team
- Follow a launch request
- Distinguish view from execution
Before you start
- Node 22 or 24 and tmux on a supported host
- One working provider account and a disposable repository
Turn the first owner/checker run into evidence for a safe rollout decision
Key takeaways
- Declarative topology and live readiness are different states.
- SQLite tracks coordination while tmux hosts provider terminals.
- Viewer lifetime is not seat lifetime.
Compile the declared team
A RigSpec declares pods, members, edges and continuity. AgentSpecs provide reusable guidance, skills, hooks, profiles and startup contracts. Previewing the spec shows the intended topology before any seat is launched.
These declarations are configuration, not a guarantee that accounts authenticate or startup contracts complete. Compare the planned graph with live `rig ps --nodes` output after launch.
Follow a launch request
The CLI sends an up request to the local daemon. The daemon coordinates domain services and persists state in SQLite while tmux sessions and runtime adapters host the actual provider processes. The kernel provides separate operational support.
A seat keeps its logical identity even if a provider session is replaced. That lets a reviewer address the same role, but context continuity and restored runtime state still need inspection after a restart.
Distinguish view from execution
The TUI draws a graph and table of seats. herdr or cmux can arrange terminals, while tmux remains the underlying session layer. The older React web UI is described as maintenance mode.
When a display fails, ask whether the daemon, tmux session, runtime adapter or viewer failed. Restarting the whole rig because a viewing terminal closed risks duplicating work.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Inspect RigSpec and AgentSpec independently.
- 2
Compare a planned graph with live seats.
- 3
Diagnose daemon, tmux, runtime and viewer separately.
Copy-ready example
RigSpec + AgentSpec -> CLI up plan
CLI / MCP / TUI -> daemon -> SQLite
daemon -> tmux seat -> provider runtimeFrequently asked questions
Is the TUI the agent runtime?
No. It observes state; tmux and runtime adapters host the sessions.
Does one seat always equal one unchanged conversation?
No. The stable role can survive a change of occupying session.
Sources
- OpenRig / README.mdSource checked 2026-10-04
- OpenRig / docs/reference/rig-spec.mdSource checked 2026-10-04
- OpenRig / docs/reference/agent-spec.mdSource checked 2026-10-04
- OpenRig / packages/cli/src/commands/up.tsSource checked 2026-10-04
- OpenRig / docs/reference/instance-layout.mdSource checked 2026-10-04