Configuration

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

Most of what looks fixed about OpenRig is a typed setting: where the work tree lives, how often snapshots are taken, when a seat counts as stalled, the context-pressure thresholds that raise a health finding. rig config with no arguments prints every key, its current value and where that value came from. Resolution is CLI flag, then environment variable, then config file, then default, and --with-source names the winner per key. A source of default means derived on this machine, not a universal constant; paths in particular differ per installation.

Permission posture is a different thing. OpenRig records a posture into the rig spec and never enforces allow, ask or deny at runtime; the harness's own permission settings are the control surface. rig policy teaches and records that posture. rig mode inspects and sets the scoped operating posture, human-led or delegated, and grants no authority by itself.

The three commands you will use first

See everything, with provenance.

rig config
rig config --with-source
rig config --json

Read or change one key. Use the key instead of hardcoding a path.

rig config get daemon.port
rig config get workspace.root --show-source
rig config set snapshots.periodic.interval_seconds 600
rig config reset snapshots.periodic.interval_seconds

Scaffold a workspace.rig config init-workspace lays down the canonical project scaffold additively on a machine that has none.

rig config init-workspace

Every configuration key

The full key table is generated from the running binary and lives in the generated reference: see generated/config-keys.md (67 keys, with type, reported default and the source layer that won on the generation host). Defaults that are host-derived paths or names are redacted there on purpose; document them as derived, never as constants.

The config family

Command	What it does (from help)	Help source
rig config	Inspect and change OpenRig configuration	config.txt
rig config get	Read a single config value	config.get.txt
rig config init-workspace	Scaffold a repo-ready project workspace	config.init-workspace.txt
rig config reset	Clear a config override (or delete the entire file when no key given)	config.reset.txt
rig config set	Set a config value	config.set.txt
rig mode	Inspect and explicitly set scoped operating posture (human-led/delegated) and operator-context modes.	mode.txt
rig mode cite	Emit a citation line for the effective mode at a read context. Per convention §Citation Rules.	mode.cite.txt
rig mode defaults	Print the recommended per-mode 8×7 + default-scope + stale rule.	mode.defaults.txt
rig mode effective	Inspect effective operating posture, scope, phase and source. Resolved unset scopes default to human-led; unreadable or ambiguous identity stays unknown.	mode.effective.txt
rig mode set	Propose a mode binding. Without --confirm, restates the proposed binding and exits 2 (no daemon write). With --confirm, sets it.	mode.set.txt
rig mode show	List all operator-context-mode bindings.	mode.show.txt
rig mode unset	Delete one binding (operator-only). Scope: global_host / rig / project / mission / workstream / qitem.	mode.unset.txt
rig policy	Teach and record the rig-level permission policy. OpenRig bakes NO allow/ask/deny permission policy , the harness-native permissions are the control surface. OpenRig records posture into RigSpec; harness-native permissions enforce , never runtime enforcement. (The context-mode verb formerly at this name is now: rig mode.)	policy.txt
rig policy apply	Record a policy choice into an EXISTING rig spec (the same recording flow as rig setup --policy, which stays as the setup-step composition). OpenRig bakes NO allow/ask/deny permission policy , the harness-native permissions are the control surface. OpenRig records posture into RigSpec; harness-native permissions enforce , never runtime enforcement.	policy.apply.txt
rig policy current	Show the EFFECTIVE permission policy for a rig spec and what would apply, per site (rig + member overrides), through the authoritative validator/resolver.	policy.current.txt
rig policy list	List the built-in permission-policy templates, plus the custom policies visible in a spec context. OpenRig bakes NO allow/ask/deny permission policy , the harness-native permissions are the control surface. OpenRig records posture into RigSpec; harness-native permissions enforce , never runtime enforcement.	policy.list.txt
rig policy show	Show one built-in policy choice, or validate + open a CUSTOM policy spec by ref (relative to --spec's directory, else cwd).	policy.show.txt

What it does not do

• It does not grant or deny permissions. rig policy records posture; the harness enforces.
• rig mode set without --confirm only restates the proposed binding and exits 2; nothing is written.
• Changing startup-time roots (the files allowlist, progress scan roots) needs a daemon restart; most other keys do not.
• A reported default is what this installation derived. Do not copy it into another machine's docs as a constant.

Where it goes next

• Troubleshooting: what to check when the daemon and the CLI disagree about where the work tree is.
• The terminal UI: the system and config views browse the same keys.

Read as Markdown