Cross Host Rig Commands

Cross-host rig commands

Use a registered host address and the entry's declared transport. SSH entries run a remote CLI through a single-hop shell; HTTP entries use the remote daemon. These paths have different prerequisites and command coverage. Check the exact command's help and the target installation before a consequential operation.

Choose and inspect the destination

rig host list shows registered hosts. rig host add --help describes registry writes; rig host doctor --help describes reachability checks. Inspect the configured OpenRig home rather than assuming the default ~/.openrig/hosts.yaml. Registry changes affect later routing, so make them within the requested scope.

hosts:
  - id: test-vm
    transport: ssh
    target: test-vm.local
    user: example-user
  - id: remote-dev
    transport: http
    url: http://remote-dev.example:7433
    bearer_env: REMOTE_RIG_TOKEN

The registry requires a hosts array, unique non-empty ids and a supported transport. SSH needs a non-empty target; user and notes are optional. HTTP needs a URL and accepts at most one of bearer_env or bearer_file. Omitting both is valid for a tokenless target. A configured but unavailable bearer is a permission failure, not anonymous fallback. Host ids also have reserved-name validation; use the actual validator's error rather than inventing an alias that collides.

Address the intended operation

rig send dev-worker@example-rig "check the assigned result" --host remote-dev --verify
rig capture dev-worker@example-rig --host remote-dev
rig ps --host remote-dev --nodes --json
rig whoami --host remote-dev

These coordination commands select SSH or HTTP from the registry entry. They do not silently try another transport when one fails. A host-qualified target can be convenient, but confirm its parsing and any persisted host selection with the particular command. Explicit --host is preferable for consequential cross-host work.

Queue destinations use explicit --host or a supported host-qualified destination; queue writes do not follow persisted host selection. The CLI separates the host from the canonical seat in the routing envelope. Different queue subcommands have different flags: check their help instead of copying a flag from send. A local success message alone does not establish remote persistence or pickup.

Read failures at the layer that failed

The exact result taxonomy depends on the path. HTTP failures expose the remote status/error; SSH distinguishes the shell transport from the remote command. Do not start or replace a remote daemon merely because a diagnostic suggests it; first establish the target's state and the authority for that lifecycle action. A timed-out write may have reached its destination. Reconcile its durable effect before retrying.

Verification and attribution

Transport success is not delivery verification or agent consumption. SSH forwards --verify and returns the remote CLI result. HTTP preserves the remote transport verdict and explicitly reports that the local pane-effect check did not run cross-host. Inspect that result and the destination effect required by the task; never replace it with “SSH exited zero” or “HTTP returned successfully.”

Cross-host output names the host/target; JSON envelopes carry cross_host metadata. The precise envelope differs by command and transport. Preserve the underlying remote result when passing evidence onward.

A target's host suffix selects a destination; a sender's origin identifies where a reply belongs. Use the rendered reply address and verify its host mapping. Current send derives the sender from the executing seat context, not a caller's --from assertion. It adds origin-host identity at cross-host forwarding; do not assume local sends have the same suffix. Unknown identity remains unknown.

This guide describes the implemented command paths, not proof of a live remote journey on your installation. Forks, handovers and other lifecycle compositions need their own supported command and scoped authority; reading remote state does not authorize them.

See also

• openrig-user — exact command reference
• seat-continuity-and-handover — stable seat and occupant outcomes