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. This is owner/admin-only because it mints a short-lived runner pairing session that leads to machine credentials.
• 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.
• Diagnose (DER-949): rost runner diagnose --runner-id <id> / runner.diagnose / rost_diagnose_runner returns health, capabilities, and repair guidance without exposing secrets. Use when a runner is offline or stale to get actionable next steps.
• Repair steps (DER-949): rost runner repair --runner-id <id> [--issue restart|re_pair|revoke_stale|missing_cli_runtime] / runner.repair / rost_repair_runner returns focused repair instructions. The optional issue flag narrows to a specific kind of repair (restart the app, re-pair, revoke a stale runner, or install a missing CLI runtime).
• 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/admin 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.pairing.start, work_order.enqueue, and agent.run_now are none, so they do not create a separate pending confirmation, but runner.pairing.start is still owner/admin-only at the command authorization layer. runner.revoke and work_order.cancel are human_required. 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.