# Lifecycle: a rig you can grow and shrink while it runs

Documented against OpenRig 0.5.14. Help text uses "node" where these pages say **seat**, for a seat's position in the running rig.

## What it is for

A rig is a describable thing: one spec, booted as one unit, changed while it runs, stopped and brought back by name. You do not tear a rig down to add a seat, and you rarely start from nothing. The library ships starters you can boot by name; a working topology can be exported to a spec later; sessions you started by hand can be discovered and adopted into a rig without restarting them.

## The three verbs you will use first

**Boot a starter, or your own spec.** The source is a library name, a path to a `rig.yaml`, or a `.rigbundle`. `--plan` previews without executing.

```
rig up first-project
rig up ./rig.yaml --plan
rig up secrets-manager
```

**Grow it while it runs.** `rig grow` adds one or more seats by name to an existing pod, or a new pod with `--new-pod`; `--runtime` defaults to claude-code and `--cwd` defaults to the current directory. `rig add` does the same from a member fragment file.

```
rig grow my-rig reviewer-2 --pod review
rig grow my-rig indexer --new-pod index --runtime codex
```

**Stop it, or one seat of it.** `rig down` tears the rig down. A running rig attempts a snapshot before teardown on its own; `--snapshot` states that intent explicitly, and a failed snapshot is reported without stopping the teardown. Help uses "node" where this page says seat, for a seat's position in the running rig. `rig launch <rig> [seat]` starts or restarts one seat without disturbing the rest. `rig remove` takes one seat out; if it holds active work, `--fallback <live-seat>` reroutes the rows first, and without a valid fallback the command refuses rather than strand them.

```
rig down my-rig --snapshot
rig launch my-rig dev.impl
rig remove my-rig dev.qa --fallback dev.impl
```

## Identifiers, in one place

Three spellings appear in help and they name different things. A seat's **session address** is `pod-member@rig`, for example `dev-impl@my-rig`; it is what `rig send`, `rig capture` and `rig transcript` take. A seat's **logical id** inside a rig is `pod.member`, for example `dev.impl`; it is what `rig launch`, `rig remove` and `rig bind --node` take, and help calls it a node ref. When you adopt sessions you started by hand, `--bind` pairs the two: `--bind dev.impl=my-tmux-session` maps a logical id to the tmux session or discovery id that will occupy it.

## The rest of the family

`rig discover` scans for tmux sessions OpenRig is not managing; `--draft` writes a candidate spec from them. `rig adopt <spec> --bind <logicalId=session>` materializes a topology and binds those live sessions into it in one step; `rig bind` wires one discovered session to one node. `rig attach` puts the shell or agent you are running in under management, so it has an address. `rig fork <session>` copies a live seat's context into a new seat, one-shot by default, `--keep-image` to keep a durable image. `rig expand` and `rig shrink` add or remove a whole pod. `rig archive` hides a finished rig from the default view and keeps all its data; `rig unarchive` reverses it. `rig release` and `rig unclaim` stop managing adopted sessions without killing the process or the agent inside it. `rig reconcile-session` makes the daemon see a seat you resumed by hand.

[//]: # (table:start)
| Command | What it does (from help) | Help source |
|---|---|---|
| `rig add` | Add a member to an existing pod in a running rig | add.txt |
| `rig adopt` | Materialize topology and bind discovered live sessions | adopt.txt |
| `rig archive` | Archive a rig (soft + reversible: hides it from the default view, retains all data). NOT a delete; reverse with 'rig unarchive'. | archive.txt |
| `rig attach` | Attach the current shell or agent into a rig node | attach.txt |
| `rig bind` | Bind a discovered session to a rig node (existing or new) | bind.txt |
| `rig create` | Create a one-seat rig without writing a spec | create.txt |
| `rig discover` | Scan for unmanaged tmux sessions | discover.txt |
| `rig down` | Tear down a rig | down.txt |
| `rig expand` | Add a pod to a running rig | expand.txt |
| `rig fork` | Fork a live seat's context into a new seat (composes the shipped agent-image fork path) | fork.txt |
| `rig grow` | Add one or more seats to a running rig | grow.txt |
| `rig launch` | Launch or relaunch a node in a running rig | launch.txt |
| `rig reconcile-session` | Adopt a live, hand-resumed session back into its persisted node (no launch, no input) | reconcile-session.txt |
| `rig release` | Release claimed sessions from a rig without killing tmux sessions | release.txt |
| `rig remove` | Remove a node from a running rig | remove.txt |
| `rig shrink` | Remove an entire pod from a running rig | shrink.txt |
| `rig unarchive` | Unarchive a rig (reverse of 'rig archive'): returns it to the default view. Always safe. | unarchive.txt |
| `rig unclaim` | Release an adopted session without killing the tmux session | unclaim.txt |
| `rig up` | Launch a rig or managed app from a spec, library entry, or bundle | up.txt |

[//]: # (table:end)

## What it does not do

- `rig down` kills the tmux sessions OpenRig launched. A daemon-only restart preserves them; do not reach for `down` to tidy up.
- `unclaim` and `release` here stop managing a live session. The queue has verbs with the same names that put a work row down. Same word, different blast radius.
- A boot does not verify that the agents know anything when they arrive. `rig spec audit` asks that question before launch (see the Specs pages).
- Discovery reads names and working directories; it does not infer roles beyond what `--draft` writes into the candidate spec for you to edit.

## Where it goes next

- [Continuity](/docs/continuity): snapshots, restore, handover and compaction for what you just booted.
- [Specs](/docs/specs-edits): the `rig.yaml` behind the starter, and how to write your own.
- [Hosts](/docs/hosts-and-humans): the same verbs on another registered machine with `--host`.