Local runner guide

The local runner is for human-controlled local agent work. It should retrieve ROST context, use narrow tokens, and report work back through audited MCP or CLI commands.

Runner sequence

1. Create a scoped token. 2. Fetch the agent-reference-map. 3. Fetch the seat or onboarding context. 4. Draft changes before activation. 5. Record work, Friction, handoffs, and escalations. 6. Revoke access when the session ends.

Inspect and control runners from CLI or MCP

• Pair a new runner: runner.pairing.start / rost_start_runner_pairing with name and platform returns a human pairing code.
• Inspect: rost runner list --json / runner.list / rost_list_runners shows online/offline/revoked state; rost runner status / runner.status / rost_runner_status reads one runner.
• Work orders: rost runner work-orders / work_order.list / rost_list_work_orders; queue with work_order.enqueue / rost_enqueue_work_order for a live scheduled agent, or use agent.run_now / rost_run_agent_now when an operator wants the product to queue and dispatch an immediate live run from a seat id; cancel with work_order.cancel / rost_cancel_work_order.
• Revoke: rost runner revoke / runner.revoke / rost_revoke_runner so a runner can no longer authenticate.

Owner-initiated headless pairing

Use this flow when a headless or desktop runner cannot use the interactive web confirmation flow.

1. The owner runs runner.pairing.start or rost_start_runner_pairing with the runner name and platform. 2. The owner gives the returned user_code to the runner through a trusted out-of-band channel. 3. The runner calls POST /api/runner/pairing/claim with {"user_code":"ABCD-2345"}. 4. The response returns runner_id, runner_secret, name, and platform. Store the runner secret only on the runner machine. 5. The runner sends heartbeats with Authorization: Bearer <runner_secret> and then claims work orders.

When to stop for confirmation

runner.revoke and work_order.cancel are human_required; runner.pairing.start, work_order.enqueue, and agent.run_now are none, so an operator can pair a runner and queue work directly. List and status reads are not gated. Revoking a runner or cancelling work is the human-approved act. An agent inspects runner state and proposes the action.

Guardrails

The runner should not store raw credentials in local notes, prompts, or logs. It should not treat local tool availability as permission. ROST server guards remain authoritative.