OpenRig

A harness wraps a model. A rig wraps your harnesses. Define your agent team in YAML, boot it with one command. Claude Code and Codex in the same rig, managed as one system.

OpenRig is open-source software for building and running your own network of agents. It turns AI coding agents from a pile of terminal sessions into a persistent, organized team. Talk to a lead agent about the outcome you want; it can coordinate specialists across teams and bring you results and decisions that need your attention. Start with a repository and one useful change, then keep the team's work and context at the same addresses.

It's the open-source system behind my AI civilization experiments.

Guide: Getting started · Stuck? Help · Questions: Q&A · Updates and demos: @_feralmachine on X

See it running

Start here: the guided first-use path: install, talk to the kernel operator, then choose a team for your first useful change.

Not setting this up today? Get the next walkthrough and occasional OpenRig updates → https://openrig.dev/follow

Install and first run

Requires Node.js 22 or 24 and tmux, on macOS or Linux. On Linux, the distribution's own Node.js can be older (Ubuntu 24.04's is 18); install a supported version with nvm (nvm install 22) or NodeSource. On a Mac with Apple silicon, use Node.js 22 (compatibility history). On Windows, use WSL2, the Windows route OpenRig supports; native Windows isn't supported. OpenRig's automated tests don't run on WSL2 yet; see one user's working setup. Launching a rig writes provider hooks and workspace trust settings. Before running the commands below, read what OpenRig changes on your machine and back up the relevant files.

One command. This runs OpenRig's install script from the v0.6.6 release. It checks Node.js and npm, installs the latest published @openrig/cli with npm install -g, runs the Node.js and SQLite check, then runs rig setup --dry-run and rig setup. The first line prints that plan and changes nothing:

curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.6/scripts/install.sh | sh -s -- --dry-run
curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.6.6/scripts/install.sh | sh

If a provider isn't signed in yet, the last step reports FAILED [4/4], and rig setup lists the sign-in under "Some steps need attention". If the only remaining failures are provider sign-ins, the install steps finished; sign in to each selected provider as below and continue.

Or step by step:

npm install -g @openrig/cli
rig setup --dry-run

To install with Bun instead, run bun add -g @openrig/cli. OpenRig still runs on Node.js, so install Node.js 22 as well. Bun may block this package's postinstall script, in which case the Node.js and SQLite check described under what OpenRig changes on your machine does not run at install time.

npm 11 and later can skip that postinstall script and print npm warn install-scripts naming @openrig/cli. That's expected: the CLI still works, and only the Node.js and SQLite check was skipped. To run it yourself, use node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"; rig doctor checks the Node.js version only.

Choose the working account you already have: Claude Code, Codex, or both. Reuse an explicit choice; no second subscription is required. rig setup --dry-run previews the broader setup; applying rig setup checks both harnesses and installs a missing one, plus Herdr unless declined with --no-herdr. On macOS, the installing agent offers Ghostty once. Setup leaves an existing cmux installation alone. It is optional for the selected-provider path.

A team seat with no permission policy, per-seat choice or (for Codex) named profile launches with OpenRig's team default: Claude runs ordinary rig commands, project reads and common tests without prompting, while lifecycle commands such as rig up and rig down still ask; Codex also gets the OpenRig workspace and its pod's state directory as writable directories. Before launching, your agent recommends keeping that default, and offers to remember selected OpenRig commands in your native settings only if you want that, at personal project scope unless you explicitly choose user-wide sessions. It is not global YOLO or permission to invent work. On Yes, the agent adds and verifies native rules; No or no answer keeps the team default and leaves settings unchanged. An existing explicit choice is reused. Say “Undo the OpenRig command allowances added by this setup” to remove only its additions.

If permission prompts are slowing you down, consider the workshop bundle. It ships with broad access and non-interruptive mode: its agents bypass permission prompts and supported harness warning dialogs. The listing and before-install view explain that access before you choose it.

Check tmux -V and only your selected CLI/login: claude --version plus claude auth status, or codex --version plus codex login status. If needed, sign in once with claude auth login or codex login; do not install or log in to an unused provider.

Your agent opens OpenRig for you

After installing, your agent opens the OpenRig TUI and the operator for you. To get back to them later, ask your agent for OpenRig or your agents in any words. After checking the selected login, it runs:

rig daemon start  # if stopped
rig terminal open saved:kernel --window

--window opens a new terminal tab or window itself, or a space in your current Herdr session. Below 120 measured columns, the operator fills the first page; from 120, the dashboard and operator share it equally. The advisor has a separate tab or tmux window. An installing agent can run it from its shell on the daemon's desktop; the person copies nothing. It uses Herdr when installed, otherwise the same layout in plain tmux, and preserves existing conversations. rig tui is the team dashboard. Installation is finished when you are talking to the operator; if you choose to talk later, that handoff remains pending.

If setup stops, read the named step: missing tools and selected-provider logins need their specific setup action. A harness permission rule, sandbox or automatic permission decision can also block the installing agent's command. The agent should name the command and reported reason, then help you resolve that specific step within your chosen permissions. A permission refusal is not an OpenRig installation result.

The desktop may need an Automation approval; SSH/headless sessions may have no display. Herdr can show first-run panels, and an 80×24 window can cramp the view. Follow the OpenRig view checks and next steps. Herdr is visible only inside a terminal you can see. Changing the shared TUI to :terminals does not open that terminal. The agent checks the visible window when it has desktop access and says what it could not verify otherwise. Over headless SSH, it asks you to open a new terminal window or tab and gives the exact connection and attachment command for the current view. If you choose a manual attachment after a failure, ask the installing agent for the exact command using your current operator session; run that in a new terminal window.

The kernel's operator helps you pick a first team. It asks what you want to build, recommends one of three, and fits it to the providers you have.

As shipped, starter uses both Claude Code and Codex. With only one of them, ask the kernel operator to adapt it: it writes a copy of the team for your providers under the same name. first-project is starter's old name and still starts it, unless you already have a rig named first-project or starter: then it refuses and names the rig up <name> --existing command that brings that rig back. Show the selected runtime, configured model and command before launch; confirm the account supports the model instead of silently falling back. The kernel starts automatically and selects from available authenticated providers independently of these teams. A missing unused provider is n