ruos

# ruOS **An agentic desktop — a desktop that runs itself.** ruOS is a full Linux desktop with the entire [ruvnet](https://github.com/ruvnet) AI-agent stack built in: it acts on its own — research, writing, code, system tasks — instead of waiting for every click. It happens to run in the cloud and be reachable from any browser, an installable iPad app, or a native macOS app, but the identity is **agentic**, not "a cloud desktop." Nothing to install to use it; a real desktop to drive when you want one. This repo is the public control-and-extension surface for a ruOS desktop: - **[`mcp/`](./mcp/)** — the ruOS **computer-use MCP server**: screenshot, keyboard/mouse, `run_shell`, `system_action`, and `desktop_resolution`. Point Claude (or any MCP client) at a ruOS desktop and let it drive. - **[`skills/`](./skills/)** — the ruvnet-stack **skills** you run on a ruOS desktop: swarm orchestration, vector memory, self-learning hooks, and the RuVector memory substrate. > Served at **[ruos.cognitum.one](https://ruos.cognitum.one)** · Powered by > [Cognitum](https://cognitum.one). --- ## What ruOS is ruOS is an **agentic desktop**: a full GNOME Linux desktop with the ruvnet AI-agent stack wired in as a first-class control plane, so agents drive the machine — screen, keyboard, shell, and system actions — the same way you do. It runs on a VM and is streamed to you over a remote-desktop transport; you reach it three ways, all against the same desktop: - **Browser** — a rebranded [noVNC](https://novnc.com) viewer at `ruos.cognitum.one/vnc.html`. No install, any device. - **iPad** — an installable PWA (`ruos.cognitum.one/ipad/`); a native SwiftUI app is on the roadmap. - **macOS** — the **ruOS Connect** app (native RustDesk-based viewer). On top of the desktop sit two control surfaces this repo documents: - The **MCP control plane** ([`mcp/`](./mcp/)) — an AI client drives the desktop (pixels, keyboard, shell, system actions) over stdio-over-SSH. - The **skills** ([`skills/`](./skills/)) — the ruvnet stack (Ruflo + RuVector), invoked from a terminal or an attached MCP client. ## Architecture ``` Browser (noVNC) ┐ iPad PWA ├─► ruos.cognitum.one ──► ruOS desktop VM macOS Connect ┘ (viewer front) (GNOME on Xorg) │ Claude / MCP client ── stdio over SSH ──► ruos-mcp ──► xdotool / scrot / shell │ executor (127.0.0.1:17870) │ system_action, desktop_resolution ruvnet stack (Ruflo, RuVector) ── skills ``` - **Viewer front** — a viewer served over HTTPS (Caddy + Let's Encrypt). Works standalone (direct) today; a per-tenant OAuth + id→desktop routing tier is the hosted-mode direction (see Roadmap). - **MCP control plane** — [`mcp/ruos-mcp`](./mcp/) exposes 16 computer-use tools. Transport is **stdio over SSH**: the security boundary is who can open the SSH session, not an open port. - **Executor** — a desktop-local server on loopback `127.0.0.1:17870` runs named system actions and the resolution change; the MCP server proxies to it. - **Skills** — the ruvnet stack preinstalled on the desktop; see [`skills/`](./skills/). ## OS ruOS is an **agentic desktop**, not merely a remote/cloud desktop: the base is a conventional Linux desktop, and what makes it ruOS is the ruvnet AI-agent stack and MCP control plane layered on top so the machine acts on its own. The hosting below is an implementation detail of *where* it runs, not the product identity. | Aspect | Detail | |--------|--------| | **Base** | Ubuntu 24.04 LTS (`ubuntu-2404-lts-amd64`) on a GCP Compute Engine VM | | **Desktop** | GNOME on Xorg, with `xf86-video-dummy` (virtual display `DUMMY0` — no physical GPU/framebuffer on a GCE instance) | | **Transport** | RustDesk (native/macOS) and x11vnc→noVNC (browser); server-side resolution via `xrandr` | | **Stack** | ruvnet AI stack — Ruflo (`@claude-flow/cli`) + RuVector (`ruvector`), plus the `ruos-mcp` computer-use server | | **Region** | GCP `northamerica-northeast2` (Toronto) — chosen for low interactive-streaming latency | ### Tiers (cpu / gpu) One machine-profile variable selects the tier (ADR-009 of `ruos-desktop`): | Tier | Machine | Encode | Notes | |------|---------|--------|-------| | **cpu** (default) | `e2-standard-4` (4 vCPU / 16 GB) | Software VP9 | Cost-sensitive; BBR/fq + tuned buffers, animations off | | **gpu** (opt-in) | `g2-standard-4` (+ NVIDIA L4) | Hardware NVENC H.264/H.265 | ~6× the cpu cost; GPU also free for local inference | A scheduled stop/start (weekday 07:00–23:00, Toronto) keeps the cpu tier around ~$50/mo (ADR-002). Flipping tiers is an in-place machine-type change, not a rebuild. ### Multi-tenant The **direction** is a multi-tenant hosted SaaS: sign up, get your own private ruOS desktop, reach it from any device. That model is **not fully shipped** — today a desktop runs in single-operator mode; per-tenant OAuth (Cognitum OIDC), id→desktop routing, signup capture, and usage metering are on the roadmap. The viewer is designed so hosted auth is a **wrapping tier that can be enabled or disabled**, never baked into the core viewer. ## Quickstart ```bash # 1. Build the MCP server (see mcp/README.md for musl + deploy notes) cd mcp && cargo build --release # → target/release/ruos-mcp # 2. Point Claude Code at a ruOS desktop (stdio over SSH) claude mcp add ruos -- ssh you@your-ruos-desktop \ 'DISPLAY=:0 XAUTHORITY=/run/user/1000/gdm/Xauthority /usr/local/bin/ruos-mcp' # 3. Wire the ruvnet skills into the session claude mcp add claude-flow -- npx -y @claude-flow/cli@latest ``` Then ask Claude to screenshot the desktop, run a shell command, or spin up a Ruflo swarm. See [`mcp/README.md`](./mcp/README.md) and [`skills/README.md`](./skills/README.md) for the full surface. ## Real vs roadmap **Real, today** - The `ruos-mcp` server (16 tools) — builds, handshakes, and drives a desktop over stdio-over-SSH. - The browser noVNC viewer, iPad PWA, and macOS Connect app against a live desktop. - The ruvnet skills (`@claude-flow/cli`, `ruvector`) via `npx`. - cpu / gpu machine tiers. **Roadmap** - `desktop_resolution` needs the ADR-022 executor endpoint (branch `feat/resolution-api`; ADR is *Proposed*). - Multi-tenant hosted mode: Cognitum OAuth, id→desktop routing, signup backend, usage metering. - A hosted MCP gateway (reach a desktop's MCP without an SSH account). - A native iPad (SwiftUI) app and an in-desktop skills gallery. ## Repository layout ``` ruos/ ├── mcp/ # ruos-mcp — the computer-use MCP server (Rust) │ ├── src/main.rs │ ├── Cargo.toml │ └── README.md # tool list, JSON-RPC/stdio usage, client setup ├── skills/ # ruvnet-stack skills as SKILL.md descriptors │ ├── ruflo-swarm/ ruflo-memory/ ruflo-hooks/ ruvector/ │ └── README.md ├── LICENSE # MIT └── README.md ``` ## License MIT — see [LICENSE](./LICENSE).