# Ruos Host Run

> 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.

- Skill: `ruvnet/ruos-host-run` (Agent Skill)
- Install (CLI): `npx get-skill add ruvnet/ruos-host-run`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ruvnet/ruos-host-run/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: ruvnet (https://skillmd.com/u/ruvnet)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/ruvnet/ruos-host-run

---

# 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.

1. **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.
2. **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.
3. **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.
4. **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.
5. **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.
6. **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.
7. **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.
8. **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).

