Accounts, providers and rig environments

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

What it is for

Seats run on the accounts your harnesses are already logged into. rig auth manages named auth profiles for a runtime without ever printing, logging or storing a token. rig provider reads which seats are bound to which accounts and what the usage signals say, and moves one seat to another login or credential while keeping its conversation. rig env inspects and controls the services a service-backed rig runs alongside its seats, such as the Vault behind the secrets-manager starter.

The three commands you will use first

See the auth state without secrets.

rig auth status
rig auth list --runtime codex
rig auth seats list

Read the provider model, and switch safely. rig provider status --refresh reads the Codex login's usage windows and the Claude login's identity first; usage windows show only once you turn on provider.usage_windows. precheck shows what a move would do and stops nothing. switch plans the seat's in-place restart first, so a refusal changes nothing, then restarts the seat on the new login with the same conversation: a Codex seat to a login saved in its Codex home (Linux only), a Claude seat to its own subscription token file. A Claude seat can also move to an API key on the same conversation with --api-key-file, and back with --token-file. The API-key path is not qualified yet, so check the resulting account and conversation.

rig config set provider.usage_windows true
rig provider status --refresh
rig provider precheck --seat dev-impl@my-rig --to-account <name>
rig provider switch --seat dev-impl@my-rig --to-account <label> --token-file <path>

Move a seat to the other runtime. rig seat set-runtime moves a live seat between Codex and Claude Code: the successor starts first, reads a handover and confirms it, then the old runtime retires. The seat keeps its address, queue rows and claims; --dry-run shows the plan.

rig seat set-runtime dev-impl@my-rig --runtime claude-code --reason "move to Claude" --dry-run

Check a service-backed rig's environment. env status is the honest health surface for managed services; ps alone is not.

rig env status secrets-manager
rig env logs secrets-manager vault
rig env down secrets-manager

The auth, provider and env families

Command	What it does (from help)	Help source
`rig auth`	Manage agent auth profiles (CLI-local; runtime via --runtime). Tokens are never printed, logged, or stored.	auth.txt
`rig auth list`	List saved profiles by name.	auth.list.txt
`rig auth save`	Snapshot the active auth state into a named profile (file copy; contents never echoed).	auth.save.txt
`rig auth seats`	Seat -> profile registry (metadata only; not proof of a live account).	auth.seats.txt
`rig auth seats list`	List seat -> profile mappings.	auth.seats.list.txt
`rig auth seats report`	Counts: total / known / unknown / malformed.	auth.seats.report.txt
`rig auth seats set`	Upsert a seat -> profile metadata row.	auth.seats.set.txt
`rig auth seats show`	Show the registry row for one seat.	auth.seats.show.txt
`rig auth status`	Auth-file presence + login state (no secrets).	auth.status.txt
`rig auth switch`	Restore saved credential bytes (sign-in is unverified).	auth.switch.txt
`rig auth validate`	Check a profile's file mode + JSON parseability (NOT live-auth).	auth.validate.txt
`rig env`	Inspect and control rig environment services for service-backed rigs and managed apps	env.txt
`rig env down`	Stop a rig's services as its down_policy says; --volumes also removes volumes	env.down.txt
`rig env logs`	Print recent logs from a rig's services, or from one service	env.logs.txt
`rig env status`	Show the state of a rig's services	env.status.txt
`rig provider`	Provider accounts and usage signals, and moving one Codex seat to another login saved in its Codex home	provider.txt
`rig provider accounts`	The accounts block of the provider read model	provider.accounts.txt
`rig provider bindings`	The bindings block of the provider read model	provider.bindings.txt
`rig provider moves`	Recent subscription move reports on this daemon, newest first: from and to, why, and each seat's result	provider.moves.txt
`rig provider moves report`	File a report of a move you made or attempted, as a queue item to whoever asked (it moves nothing)	provider.moves.report.txt
`rig provider precheck`	Whether a seat can move to a login: its in-place restart plan (nothing is stopped) and the login saved in the Codex home it runs on	provider.precheck.txt
`rig provider signals`	The signals block of the provider read model	provider.signals.txt
`rig provider status`	The whole four-block provider read model (accounts, bindings, signals)	provider.status.txt
`rig provider switch`	Move one seat to subscription or API credentials, keeping its conversation: a Codex seat to a login saved in its Codex home (Linux only), a Claude seat to its own token file	provider.switch.txt

What it does not do

rig auth validate checks a profile's file mode and JSON shape, not that the account is live.
provider signals reports anomalies (unbound seats, accounts shared across seats), not a listing.
env down --volumes removes compose volumes; it is a data-loss action, not a stop.

Where it goes next

Lifecycle: booting a service-backed rig such as secrets-manager.
Troubleshooting: what to read when a seat's runtime is not logged in.

Read as Markdown