ruOS

An agentic desktop — a desktop that runs itself. ruOS is a full Linux desktop with the entire 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/ — 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/ — 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 · Powered by Cognitum.

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 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/) — an AI client drives the desktop (pixels, keyboard, shell, system actions) over stdio-over-SSH.
• The skills (skills/) — the ruvnet stack (Ruflo + RuVector), invoked from a terminal or an attached MCP client.

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

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.

One machine-profile variable selects the tier (ADR-009 of ruos-desktop):

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.

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.

# 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 and skills/README.md for the full surface.

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.

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

MIT — see LICENSE.