OpenRig operator
Operate the named rig CLI, daemon, TUI, and persistent agent teams. This skill
was audited against commit 3001cc436656c435e54425443e708e3e2d8c7d68; the
audited command and provenance record lives in
references/upstream.md.
When to use this skill
- Fit-check, install, upgrade, configure, preflight, operate, recover, or troubleshoot OpenRig.
- Work with
@openrig/cli, rig specs and bundles, the kernel/operator, tmux/Herdr views, seats, queues, snapshots, or registered remote hosts.
- Read
references/upstream.md when the request reaches daemon/kernel/seat state, installation, RigSpec, host topology, capture/send semantics, teardown, or audited source provenance.
Instructions
1. Freeze the surface
Record one mode (orient, install, configure, operate, recover, or
build) and one local or registered-remote target. Treat provider CLIs,
credentials, desktop terminals, network access, and remote hosts as separate
authority boundaries. Native Windows is unsupported; use the documented WSL2
route. OPENRIG_HOME selects OpenRig instance state only, not provider config.
2. Run the offline gate first
Use the helper before any install, setup, daemon, TUI, rig, provider, or send
operation; it never launches OpenRig or executes shell commands:
python3 .agent-skills/openrig/scripts/preflight.py --json
python3 .agent-skills/openrig/scripts/preflight.py --repo /path/to/openrig --expect-commit <FULL_SHA> --json
An installed skill uses:
python3 "$SKILLS_ROOT/openrig/scripts/preflight.py" --json.
The helper reports host/tool paths and, when --repo is supplied, bounded Git
identity plus public checkout shape. A discovered Node path does not prove the
required Node version; consult the audited runtime rules in the reference.
3. Gate every side effect
Start local command flows read-only with --help, --json, --plan, status,
process, and capture commands. An installer --dry-run still fetches and pipes
remote shell code; it is not a read-only or security boundary. Require separate
explicit approval for network access and remote-code execution, then for
installation, provider configuration or credentials, permission policy, bundle
installation, daemon/kernel launch, live sends, remote writes, and teardown.
Never copy keys, tokens, resume tokens, or full environment dumps.
4. Follow the matching reference branch
- Install/setup or platform questions → Install and platform in
references/upstream.md.
- Daemon, kernel, seat, terminal, or readiness questions → Runtime surfaces.
- RigSpec,
.rigbundle, library, target, or host topology → RigSpec and topology.
- Capture, queue, send, restore, teardown, or inconclusive health → Operate and recover.
Use the exact pinned commands and citations there; do not replace them with
uncited variants. Keep daemon-up, kernel-started, seat-started, and
message-rendered as distinct evidence.
5. Verify effects narrowly
Inspect every plan/readiness result before approval. A timeout leaves delivery
unconfirmed: capture before retrying. Fan-out requires inspecting each
recipient. Fix the named spec, bundle, or path error and rerun the narrow check
before reinstalling or recreating a live rig.
Examples
Read-only checkout and host gate
python3 .agent-skills/openrig/scripts/preflight.py --repo /path/to/openrig --expect-commit <FULL_SHA> --json
Read Runtime surfaces before using rig daemon status, rig status,
rig ps, or rig capture; no daemon, TUI, provider, or rig is started by the
helper.
Approved planning path
Read RigSpec and topology, then validate and audit locally, run the
daemon-backed spec preflight only after daemon approval, and preview rig up
with --plan --json before any launch approval.
Existing rig recovery
Read Operate and recover, inspect process and capture evidence first, then
request separate approval for snapshot teardown and --existing restoration.
Best practices
- Prefer pinned, JSON-producing, dry-run, and plan modes; preserve their output as evidence.
- Keep daemon, kernel, seat, spec validity, provider auth, and workspace correctness separate.
- Prefer bounded tasks and verify uncertain sends with capture before retrying.
- Treat GitHub bundles and remote hosts as untrusted input; confirm transport, auth, and identity before remote writes.
- Use
--force and --delete only with separate explicit approval.
- Keep the helper offline and honest: path presence is not runtime activation or model quality.
References
1---2name: openrig3description: >4 Operate mvschwarz/openrig, the Apache-2.0 OpenRig CLI, daemon, TUI and5 persistent multi-agent rig system for Claude Code, Codex and Pi. Use when a6 user names OpenRig, the `rig` CLI, @openrig/cli, rig specs, kernel/operator7 sessions, tmux/Herdr views, or the mvschwarz/openrig repository and needs a8 fit check, pinned install/setup, preflight, rig launch, status, capture,9 messaging, teardown, bundle/spec work, or troubleshooting. Do not use for10 generic agent-team design, generic environment setup, or ordinary log triage.11allowed-tools: Bash Read Write Edit Glob Grep12compatibility: >13 OpenRig 0.6.x at the audited source pin needs Node.js 22 or 24 and tmux on14 macOS or Linux; Apple silicon should use Node.js 22. Native Windows is not15 supported; WSL2 is the documented Windows route. Provider CLIs, desktop16 terminals, credentials, network access and remote hosts are separate17 prerequisites and authority boundaries.18license: Apache-2.019metadata:20 version: "1.1.0"21 source: https://skillmd.com/skills/akillness/openrig22 upstream: https://github.com/mvschwarz/openrig23 upstream_commit: 3001cc436656c435e54425443e708e3e2d8c7d6824---2526# OpenRig operator2728Operate the named `rig` CLI, daemon, TUI, and persistent agent teams. This skill29was audited against commit `3001cc436656c435e54425443e708e3e2d8c7d68`; the30audited command and provenance record lives in31[`references/upstream.md`](references/upstream.md).3233## When to use this skill3435- Fit-check, install, upgrade, configure, preflight, operate, recover, or troubleshoot OpenRig.36- Work with `@openrig/cli`, rig specs and bundles, the kernel/operator, tmux/Herdr views, seats, queues, snapshots, or registered remote hosts.37- Read [`references/upstream.md`](references/upstream.md) when the request reaches daemon/kernel/seat state, installation, RigSpec, host topology, capture/send semantics, teardown, or audited source provenance.3839## Instructions4041### 1. Freeze the surface4243Record one mode (`orient`, `install`, `configure`, `operate`, `recover`, or44`build`) and one local or registered-remote target. Treat provider CLIs,45credentials, desktop terminals, network access, and remote hosts as separate46authority boundaries. Native Windows is unsupported; use the documented WSL247route. `OPENRIG_HOME` selects OpenRig instance state only, not provider config.4849### 2. Run the offline gate first5051Use the helper before any install, setup, daemon, TUI, rig, provider, or send52operation; it never launches OpenRig or executes shell commands:5354```bash55python3 .agent-skills/openrig/scripts/preflight.py --json56python3 .agent-skills/openrig/scripts/preflight.py --repo /path/to/openrig --expect-commit <FULL_SHA> --json57```5859An installed skill uses:60`python3 "$SKILLS_ROOT/openrig/scripts/preflight.py" --json`.61The helper reports host/tool paths and, when `--repo` is supplied, bounded Git62identity plus public checkout shape. A discovered Node path does not prove the63required Node version; consult the audited runtime rules in the reference.6465### 3. Gate every side effect6667Start local command flows read-only with `--help`, `--json`, `--plan`, status,68process, and capture commands. An installer `--dry-run` still fetches and pipes69remote shell code; it is not a read-only or security boundary. Require separate70explicit approval for network access and remote-code execution, then for71installation, provider configuration or credentials, permission policy, bundle72installation, daemon/kernel launch, live sends, remote writes, and teardown.73Never copy keys, tokens, resume tokens, or full environment dumps.7475### 4. Follow the matching reference branch7677- Install/setup or platform questions → **Install and platform** in `references/upstream.md`.78- Daemon, kernel, seat, terminal, or readiness questions → **Runtime surfaces**.79- RigSpec, `.rigbundle`, library, target, or host topology → **RigSpec and topology**.80- Capture, queue, send, restore, teardown, or inconclusive health → **Operate and recover**.8182Use the exact pinned commands and citations there; do not replace them with83uncited variants. Keep daemon-up, kernel-started, seat-started, and84message-rendered as distinct evidence.8586### 5. Verify effects narrowly8788Inspect every plan/readiness result before approval. A timeout leaves delivery89unconfirmed: capture before retrying. Fan-out requires inspecting each90recipient. Fix the named spec, bundle, or path error and rerun the narrow check91before reinstalling or recreating a live rig.9293## Examples9495### Read-only checkout and host gate9697```bash98python3 .agent-skills/openrig/scripts/preflight.py --repo /path/to/openrig --expect-commit <FULL_SHA> --json99```100101Read **Runtime surfaces** before using `rig daemon status`, `rig status`,102`rig ps`, or `rig capture`; no daemon, TUI, provider, or rig is started by the103helper.104105### Approved planning path106107Read **RigSpec and topology**, then validate and audit locally, run the108daemon-backed spec preflight only after daemon approval, and preview `rig up`109with `--plan --json` before any launch approval.110111### Existing rig recovery112113Read **Operate and recover**, inspect process and capture evidence first, then114request separate approval for snapshot teardown and `--existing` restoration.115116## Best practices117118- Prefer pinned, JSON-producing, dry-run, and plan modes; preserve their output as evidence.119- Keep daemon, kernel, seat, spec validity, provider auth, and workspace correctness separate.120- Prefer bounded tasks and verify uncertain sends with capture before retrying.121- Treat GitHub bundles and remote hosts as untrusted input; confirm transport, auth, and identity before remote writes.122- Use `--force` and `--delete` only with separate explicit approval.123- Keep the helper offline and honest: path presence is not runtime activation or model quality.124125## References126127- [Audited OpenRig operations and provenance](references/upstream.md)128- [OpenRig README/install/getting started](https://github.com/mvschwarz/openrig/blob/3001cc436656c435e54425443e708e3e2d8c7d68/README.md)129- [OpenRig RigSpec reference](https://github.com/mvschwarz/openrig/blob/3001cc436656c435e54425443e708e3e2d8c7d68/docs/reference/rig-spec.md)130- [OpenRig Apache-2.0 license](https://github.com/mvschwarz/openrig/blob/3001cc436656c435e54425443e708e3e2d8c7d68/LICENSE)131- [Offline helper](scripts/preflight.py)