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.

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

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: snapshots, restore, handover and compaction for what you just booted.
Specs: the rig.yaml behind the starter, and how to write your own.
Hosts: the same verbs on another registered machine with --host.

Read as Markdown