# Openrig Installer

> Use when installing or upgrading OpenRig on a host, especially the V0.3.1 upgrade flow which includes the substrate-kernel → daemon-managed-kernel migration ceremony. Covers npm install, rig setup, rig daemon start (auto-boots kernel), and the canonical verification commands. NOT for ordinary kernel operation post-install — use openrig-operator skill for that.

- **Type:** Skill
- **Install:** `agentstack add skill-mvschwarz-openrig-openrig-installer`
- **Verified:** Pending review
- **Seller:** [mvschwarz](https://agentstack.voostack.com/s/mvschwarz)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [mvschwarz](https://github.com/mvschwarz)
- **Source:** https://github.com/mvschwarz/openrig/tree/main/skills/_canonical/core/openrig-installer
- **Website:** https://openrig.dev

## Install

```sh
agentstack add skill-mvschwarz-openrig-openrig-installer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OpenRig Installer

This skill teaches the operator agent how to install + upgrade
OpenRig cleanly. The V0.3.1 upgrade is the one with the migration
ceremony (substrate kernel → daemon-managed kernel); other upgrades
follow the same install / setup / start shape with no migration.

## Fresh install

```bash
npm install -g @openrig/cli
rig setup
```

`rig setup` is idempotent — safe to re-run if a step fails. It probes
host prereqs (tmux present, Node version, writable state path,
optional cmux), then invokes `rig daemon start` per the L2 factoring
(OQ-B). The daemon's start path auto-boots the kernel rig per the
V0.3.1 slice 05 kernel-rig-as-default logic.

## Verification after install

```bash
rig ps --nodes --rig kernel --json
```

Should report 4 members (advisor.lead + operator.agent +
operator.human + queue.worker) all ready. If a runtime is unavailable
the daemon picks the matching variant (`rig-claude-only.yaml` or
`rig-codex-only.yaml`); the topology stays the same shape with the
unavailable runtime omitted from the agent membership.

Entry point for chatting with the rig:

```bash
rig capture advisor-lead@kernel
```

Or click the CMUX button on the topology graph in the UI at
`/topology`.

## V0.3.1 upgrade ceremony (one-time migration)

Operators with a kernel spec stored outside the daemon-managed
location (any pre-V0.3.1 layout, typically wherever you kept your
own `rigs/kernel/` directory) must migrate to
`~/.openrig/specs/rigs/kernel/` as a one-time step during the V0.3.1
upgrade. The V0.3.1 upgrade IS the migration moment; it's not a
separate ceremony.

### Migration steps

1. **Snapshot first.** Take a snapshot of the running substrate
   kernel so the migration is reversible:

   ```bash
   rig snapshot kernel
   ```

2. **Stop the substrate kernel** (so the migration doesn't race a
   running rig):

   ```bash
   rig down kernel --snapshot
   ```

3. **Copy your existing kernel spec** into the daemon-managed
   location:

   ```bash
   mkdir -p ~/.openrig/specs/rigs/kernel
   cp -r /path/to/old/kernel-spec/* ~/.openrig/specs/rigs/kernel/
   ```

4. **Upgrade the CLI + daemon**:

   ```bash
   npm install -g @openrig/cli@0.3.1
   rig daemon stop
   rig daemon start
   ```

   At this point the new daemon detects `~/.openrig/specs/rigs/kernel.yaml`
   exists and skips the V0.3.1 builtin-kernel boot (the
   already-managed-rig branch). The substrate-rooted topology
   continues to run under daemon management.

5. **Verify** the migrated kernel matches expectations:

   ```bash
   rig ps --nodes --rig kernel --json
   ```

6. **Decommission the old copy** (only after verifying the
   daemon-managed copy works):

   ```bash
   rm -rf /path/to/old/kernel-spec
   ```

### If migration fails

The pre-step snapshot is the rollback. `rig restore 
--rig kernel` revives the prior topology. Then `npm install -g
@openrig/cli@0.3.0` rolls the CLI back and you can retry later.

## Operator agent's role in install + upgrade

The operator agent shepherds operators through these steps when the
user asks "how do I upgrade?" or "what's the V0.3.1 ceremony?". The
agent reads this skill on demand via `find-skills` — it does not
need to memorize the steps; it consults the canonical reference
(this file) and walks the operator through.

## 3-part error remediation

| What failed | Why it matters | Fix |
|---|---|---|
| `npm install -g @openrig/cli` permission denied | Global install needs writable npm prefix; macOS Homebrew default is usually writable; some custom Node installs aren't | Either fix the npm prefix permissions or use `sudo npm install -g`; check `npm config get prefix` |
| `rig setup` host prereq fail | tmux, Node version, or writable state path missing | `rig doctor` lists each missing piece + the install command; run those, retry `rig setup` |
| `rig daemon start` auth-block error | Neither Claude Code nor Codex authenticated; kernel rig requires at least one | Run `claude auth login` OR `codex login`; then retry `rig daemon start` |
| `rig daemon start` "kernel already managed" | An existing managed rig named `kernel` exists; the daemon skips builtin-boot per design | This is the expected path after migration — no action needed |
| `rig ps --rig kernel --json` returns empty | Daemon healthy but no kernel rig managed; likely the migration step copied content but did not boot | `rig up kernel` from inside `~/.openrig/specs/rigs/kernel/`; or invoke the daemon's cold-boot path explicitly |

## What this skill is NOT

- Not the canonical OpenRig command surface; that lives in the
  `openrig-user` skill.
- Not the kernel-operating-procedure for post-install daily use;
  that's `openrig-operator`.
- Not for project rigs; project rigs install themselves via `rig
  up ` after the kernel is in place.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mvschwarz](https://github.com/mvschwarz)
- **Source:** [mvschwarz/openrig](https://github.com/mvschwarz/openrig)
- **License:** Apache-2.0
- **Homepage:** https://openrig.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mvschwarz-openrig-openrig-installer
- Seller: https://agentstack.voostack.com/s/mvschwarz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.