Run a ruflo agent on a ruOS desktop (session path, ADR-405)
Transport rules — non-negotiable:
- Use ONLY the fleet MCP tools (
mcp__ruos__*, or the claude.ai ruOS connector's
equivalents) or the plugin CLI. Never call a desktop on port 17870 and never set a
Host header yourself (ruOS ADR-070: that executor has no per-tenant auth).
- Send ONLY the command strings printed by
cli.mjs build. Never compose a
desktop_exec command from task text.
CLI below is node "${CLAUDE_PLUGIN_ROOT}/scripts/cli.mjs".
desktop_exec output is framed: the first line echoes your command (▶ run: …), and the
last lines are ✓ SUCCESS… and 📝 transcript:. Every marker the desktop prints is
RUOS<nonce>_NAME, on its own line, where <nonce> is the nonce from CLI build. That
token never appears in the echoed command, so match only complete lines that start with it.
Output is capped at about 4 KiB, so poll returns 2 KiB slices.
Never call desktop_delete or secret_delete; deleting is the user's job.
- Pick the host. Call
desktop_status. Resolve the user's desktop by machine_id,
fly_machine_id or exact display_name; if it is not in that list, stop. Save the raw
JSON to a temp file (status.json) for step 4.
- Liveness. A desktop is up only if
heartbeat_status is not asleep/missing/stale
and last_heartbeat_at is recent. If it is down, ask before desktop_start (billable),
then re-poll desktop_status until the heartbeat advances.
- Auto-stop.
CLI status prints nextAutoStop (weekday 23:00 America/Toronto). If the
run could cross it, tell the user and stop unless they accept. desktop_keepawake blocks
idle autosleep only; it does not override the 23:00 stop.
- Build + record. Write the task to a file, then:
CLI build --prompt-file task.txt [--model sonnet] → JSON with runId, steps[],
poll, stop, promptSha256.
CLI record start --run <runId> --desktop "<ref>" --desktop-status-file status.json --task "<one-line summary>"
— registers the agent through ruflo's agent_spawn (with config.host) and claims
ruos-run-<runId> via claims_claim.
Before launching, call llm_route_get. Stop if the desktop has no route. If the gateway is
"unconfigured" but the route is "shared", warn and continue.
- Launch. Call
desktop_exec with each steps[i] in order (machine = the desktop's
fly_machine_id). The last step prints RUOS<nonce>_SHA:<hash> — it must equal
promptSha256, else desktop_exec the stop string and abort. RUOS<nonce>_NO_RUNNER means
claude is not installed there.
- Stream. Call
desktop_exec with poll (rebuild with CLI build --run <runId> --nonce <nonce> --offset <n> ...
as the offset grows, or use CLI run for automatic polling). Output is
RUOS<nonce>_POLL:<exit|->:<size>:<alive 0|1>:<base64>; pass the base64 to
CLI record output --run <runId> --b64 <b64> and show the decoded text. Back off 1s→5s
between empty polls — each poll is audited on ruOS and serialises behind the desktop's
run lock.
- Finish. When exit is not
- and all bytes are read:
CLI record end --run <runId> --exit <code> (agent → idle, claim released).
On failure, check desktop_status: a stopped desktop means it was auto-stopped mid-run.
- Stop early only on the user's request:
desktop_exec the stop string.
For unattended runs from a terminal, CLI run --desktop "<ref>" --prompt-file task.txt
does steps 1–7 itself (needs RUOS_MCP_URL + RUOS_MCP_TOKEN, or --transport ssh with
RUOS_SSH_KEY when ruflo runs on a same-tenant ruOS desktop).
1---2name: ruos-host-run3description: Run a ruflo swarm agent on the user's own ruOS cloud desktop through the fleet MCP, stream its output and record it in swarm state. Use when the user wants an agent to run on a ruOS desktop or places a swarm agent on a remote ruOS host.4argument-hint: "<desktop> <task>"5allowed-tools: Bash(node *) mcp__ruos__desktop_status mcp__ruos__desktop_exec mcp__ruos__desktop_keepawake mcp__ruos__desktop_start mcp__ruos__llm_route_get6metadata:7 source: https://skillmd.com/skills/ruvnet/ruos-host-run8---910# Run a ruflo agent on a ruOS desktop (session path, ADR-405)1112Transport rules — non-negotiable:13- Use ONLY the fleet MCP tools (`mcp__ruos__*`, or the claude.ai ruOS connector's14 equivalents) or the plugin CLI. Never call a desktop on port 17870 and never set a15 `Host` header yourself (ruOS ADR-070: that executor has no per-tenant auth).16- Send ONLY the command strings printed by `cli.mjs build`. Never compose a17 `desktop_exec` command from task text.1819`CLI` below is `node "${CLAUDE_PLUGIN_ROOT}/scripts/cli.mjs"`.2021`desktop_exec` output is framed: the first line echoes your command (`▶ run: …`), and the22last lines are `✓ SUCCESS…` and `📝 transcript:`. Every marker the desktop prints is23`RUOS<nonce>_NAME`, on its own line, where `<nonce>` is the `nonce` from `CLI build`. That24token never appears in the echoed command, so match only complete lines that start with it.25Output is capped at about 4 KiB, so `poll` returns 2 KiB slices.26Never call `desktop_delete` or `secret_delete`; deleting is the user's job.27281. **Pick the host.** Call `desktop_status`. Resolve the user's desktop by `machine_id`,29 `fly_machine_id` or exact `display_name`; if it is not in that list, stop. Save the raw30 JSON to a temp file (`status.json`) for step 4.312. **Liveness.** A desktop is up only if `heartbeat_status` is not `asleep`/`missing`/`stale`32 and `last_heartbeat_at` is recent. If it is down, ask before `desktop_start` (billable),33 then re-poll `desktop_status` until the heartbeat advances.343. **Auto-stop.** `CLI status` prints `nextAutoStop` (weekday 23:00 America/Toronto). If the35 run could cross it, tell the user and stop unless they accept. `desktop_keepawake` blocks36 idle autosleep only; it does not override the 23:00 stop.374. **Build + record.** Write the task to a file, then:38 - `CLI build --prompt-file task.txt [--model sonnet]` → JSON with `runId`, `steps[]`,39 `poll`, `stop`, `promptSha256`.40 - `CLI record start --run <runId> --desktop "<ref>" --desktop-status-file status.json --task "<one-line summary>"`41 — registers the agent through ruflo's `agent_spawn` (with `config.host`) and claims42 `ruos-run-<runId>` via `claims_claim`.43 Before launching, call `llm_route_get`. Stop if the desktop has no route. If the gateway is44 "unconfigured" but the route is "shared", warn and continue.455. **Launch.** Call `desktop_exec` with each `steps[i]` in order (`machine` = the desktop's46 `fly_machine_id`). The last step prints `RUOS<nonce>_SHA:<hash>` — it must equal47 `promptSha256`, else `desktop_exec` the `stop` string and abort. `RUOS<nonce>_NO_RUNNER` means48 `claude` is not installed there.496. **Stream.** Call `desktop_exec` with `poll` (rebuild with `CLI build --run <runId> --nonce <nonce> --offset <n> ...`50 as the offset grows, or use `CLI run` for automatic polling). Output is51 `RUOS<nonce>_POLL:<exit|->:<size>:<alive 0|1>:<base64>`; pass the base64 to52 `CLI record output --run <runId> --b64 <b64>` and show the decoded text. Back off 1s→5s53 between empty polls — each poll is audited on ruOS and serialises behind the desktop's54 run lock.557. **Finish.** When exit is not `-` and all bytes are read:56 `CLI record end --run <runId> --exit <code>` (agent → idle, claim released).57 On failure, check `desktop_status`: a stopped desktop means it was auto-stopped mid-run.588. **Stop early** only on the user's request: `desktop_exec` the `stop` string.5960For unattended runs from a terminal, `CLI run --desktop "<ref>" --prompt-file task.txt`61does steps 1–7 itself (needs `RUOS_MCP_URL` + `RUOS_MCP_TOKEN`, or `--transport ssh` with62`RUOS_SSH_KEY` when ruflo runs on a same-tenant ruOS desktop).