Documentation

Getting Started

OpenRig is a local control plane for multi-agent coding topologies. It lets you set up, manage, monitor, and restore teams of AI coding agents that work together - defined in YAML, managed from one CLI.

What OpenRig Does

You say “I want a dev pair (implementer + QA), an orchestrator, and a review team.” OpenRig creates the tmux sessions, launches the agents, gives them their role-specific instructions, connects them to each other, and shows the whole topology in a browser dashboard. When something breaks, OpenRig snapshots and restores the entire topology.

# The product loop
down (auto-snapshot) → up <rig-name> (auto-restore) → work → repeat

# Boot a topology
rig up my-rig.yaml

# Check node status
rig ps --nodes

# Shut down (auto-snapshots first)
rig down <rigId>

# Restore from name (finds latest snapshot)
rig up my-rig

Two Users, Always Together

The Human

Directs the work. Decides what to build, which agents to spin up, when to snapshot. Monitors the dashboard. Steps in when something needs a judgment call.

The Coding Agent

Drives the CLI. Runs rig up,rig ps,rig restore. Reads error messages, adapts, retries. The CLI is designed for this user - a 10x staff engineer at the terminal.

The relationship: Human directs agent. Agent drives CLI/UI. System is honest to both levels - the agent needs accurate error messages, the human needs accurate dashboard state.

Core Concepts

AgentSpecA portable, reusable single-agent blueprint. Defines resources, profiles, startup, and lifecycle. File: agent.yaml

RigSpecA declarative topology artifact that composes agents into pods with edges, continuity policies, and layered startup. File: rig.yaml

RigBundleA portable archive bundling a RigSpec plus all vendored AgentSpecs. Machine-to-machine portability with integrity verification.

RigA desired-state control-plane object composing one or more agents into a reproducible local system. The multi-agent topology.

PodA bounded context group within a rig. Contains members (agents), pod-local edges, optional continuity policy, and pod-level startup.

Install

# Install OpenRig CLI
npm install -g @openrig/cli

# Start the daemon
rig daemon start

# Open the UI
rig ui

The daemon runs locally, manages state in SQLite, and provides the HTTP API that the CLI, UI, and MCP tools all consume.

Product Vocabulary

The product vocabulary is deliberately minimal. Five nouns, four verbs. Everything else is internal machinery.

Nouns

rigs - multi-agent topologies

agents - individual agent blueprints

pods - bounded context groups

nodes - running instances within a rig

snapshots - point-in-time captures

Verbs

up - boot or restore a rig

down - tear down (auto-snapshots first)

attach - connect to a running agent

restore - recover from a snapshot

Where To Go Next

Taxonomy

The capability layers from Model to Rig

AgentSpec

Single-agent blueprint format reference

RigSpec

Multi-agent topology format reference

Architecture

System design and execution flows

CLI Reference

All commands and their usage

MCP Tools

Machine-callable tool definitions