Accounts, providers and rig environments

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

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, what the usage signals say, and whether a seat can be switched to another account without stranding the conversation it is in. 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.precheck never offers an unsafe switch; switch is precheck-gated and orchestrated by the daemon.

rig provider status
rig provider signals
rig provider precheck --seat dev-impl@my-rig --account <ref>

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	Activate a saved profile.	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		env.down.txt
rig env logs		env.logs.txt
rig env status		env.status.txt
rig provider	Provider accounts, usage signals, and interruption-safe account switching	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 precheck	Whether switching a seat to an account is safe (never offers an unsafe switch)	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	Switch a seat to an account (precheck-gated; the daemon orchestrates the switch)	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