Run OpenRig on a remote server

On your computer (pick another name if my-openrig is taken):

ssh exe.dev new --name=my-openrig
ssh my-openrig.exe.xyz

All remaining commands run on the VM, as exedev.

Install Node.js and OpenRig#

OpenRig needs Node.js 22 or 24. Install Node.js 24 from NodeSource, and OpenRig into ~/.local, so updates need no sudo:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
npm config set prefix ~/.local
npm install -g @openrig/cli@0.7.6
rig --version

Expect 0.7.6. npm warns that it skipped an install script; that's a compatibility check, which rig doctor repeats below.

Connect Claude Code and Codex#

Point both at the LLM integration. OpenRig won't start Codex agents unless codex login status says it's signed in, so give Codex a placeholder key; the integration ignores it:

exeuntu configure claude
exeuntu configure codex
printf exe-llm-integration | codex login --with-api-key
claude -p "Reply with exactly: OK"
(cd /tmp && codex exec --skip-git-repo-check "Reply with exactly: OK")

Both should answer OK. On older VMs the first two commands are exeuntu claude configure and exeuntu codex configure.

Prepare OpenRig#

rig setup checks both agents and adds mouse support and scrollback to ~/.tmux.conf. --no-herdr skips Herdr, a terminal workspace this setup doesn't need, and --router-line no keeps an extra OpenRig line out of your projects' CLAUDE.md and AGENTS.md:

rig setup --providers both --no-herdr --router-line no
rig doctor

The doctor should end with No failures in the checks above; a warning that cmux isn't installed is fine.

Start OpenRig with the VM#

OpenRig starts its own daemon in the background. A systemd service runs rig start --last at boot, which starts the daemon and the kernel and brings back every team that was running, resuming their conversations. It only starts and stops the daemon, so restarting it leaves the agents' tmux sessions alone:

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/openrig.service <<'EOF'
[Unit]
Description=OpenRig daemon, kernel, and the teams that were running
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
WorkingDirectory=%h
ExecStart=%h/.local/bin/rig start --last
ExecStop=%h/.local/bin/rig daemon stop
KillMode=process
TimeoutStartSec=5min

[Install]
WantedBy=default.target
EOF
sudo loginctl enable-linger "$USER"
systemctl --user daemon-reload
systemctl --user enable --now openrig
rig status

The first start takes a minute while the kernel's agents start. Expect Daemon running on port 7433 and Kernel: ready. The daemon listens on 127.0.0.1 only.

Start the team#

Make the project folder (skip the git init for a folder you already have), and keep the files OpenRig adds for its agents out of git:

mkdir -p ~/project && cd ~/project
git rev-parse --git-dir >/dev/null 2>&1 || git init -b main
printf '%s\n' /CLAUDE.md /AGENTS.md /.claude/ /.mcp.json /.openrig/ >> .git/info/exclude

Describe the team. Its two agents come from OpenRig's library: an implementer that builds and verifies, and a QA agent that checks the exact change it's sent. The yolo policy lets them work without permission prompts on this VM:

mkdir -p ~/rigs/pair
cat > ~/rigs/pair/rig.yaml <<'EOF'
version: "0.2"
name: pair
summary: A Claude Code builder and a Codex reviewer on their own exe.dev VM.
permission_policy: builtin:yolo
non_interruptive: true
pods:
  - id: dev
    label: Project
    members:
      - id: build
        agent_ref: "path:/home/exedev/.local/lib/node_modules/@openrig/cli/daemon/specs/agents/development/implementer"
        runtime: claude-code
        profile: default
        cwd: /home/exedev/project
      - id: review
        agent_ref: "path:/home/exedev/.local/lib/node_modules/@openrig/cli/daemon/specs/agents/development/qa"
        runtime: codex
        profile: default
        cwd: /home/exedev/project
    edges:
      - kind: delegates_to
        from: build
        to: review
edges: []
EOF
rig up ~/rigs/pair/rig.yaml
sleep 30
rig ps --nodes --rig pair

rig up reports Status: completed, then warnings that the seats run with full bypass, as intended. Both seats should be run, with a last observed model each (Claude for build, GPT for review).

The code is the agents' work: push their branches. Everything else lives on the VM: OpenRig's database and queue in ~/.openrig, the agents' conversations in ~/.claude and ~/.codex, and the team files in ~/rigs. Copy the whole VM. On your computer:

ssh exe.dev cp my-openrig my-openrig-backup

The copy starts OpenRig and resumes the teams by itself, so use it instead of the original, not beside it, or both teams work on the same tasks. To keep a copy without running it, stop the copy's teams once with ssh my-openrig-backup.exe.xyz 'rig down pair'.

Read the changelog first, and copy the VM as above. Then, on the VM, replacing 0.7.7 with the version you want:

npm install -g @openrig/cli@0.7.7
systemctl --user restart openrig
rig --version
rig status
rig ps --nodes -A

The agents keep running through the restart; the new daemon picks them up. Don't run rig down to update. For a big jump, ask Shelley to follow OpenRig's upgrade skill.

Ask Shelley, or the operator. Or check on the VM:

rig status
rig ps --nodes -A
journalctl --user -u openrig -n 30 --no-pager
rig daemon logs | tail -n 40
rig doctor

• A seat shows needs input or attention. It's waiting at a prompt. rig capture <seat> shows it; attach with tmux attach -t <seat> and answer. If startup stopped there, run the rig seat continue <seat> that rig ps shows.
• codex_auth fails in rig doctor. Codex has no saved key: rerun the codex login --with-api-key line above.
• Readiness timeout after 30s. The agent started slowly. Run rig config set runtime.readiness_timeout_seconds 120, then rig up pair --existing.
• A team didn't come back after a reboot. rig start --last leaves down a team you stopped with rig down. Bring it back with rig up pair --existing.
• No model reply. Run the two OK checks above and check your LLM integration.
• rig: command not found. Log in again, so ~/.local/bin is on your PATH.