# roamux **Run AI coding agents on your own machines. Control them from anywhere.** Your computer stays the execution host — the agent, your repo, shell, files, git state, credentials, and model access never leave it. A phone or browser signs in and steers the agent live. [Quick start](#quick-start) · [How it works](#how-it-works) · [Contributing](CONTRIBUTING.md) · [Architecture](docs/architecture.md) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6) ![Runtime: Bun](https://img.shields.io/badge/runtime-Bun-black)
--- ## What it is roamux is a **remote control plane for AI coding agents running on machines you own**. Install a small host daemon on any computer; it dials out to the cloud and lets your authenticated devices watch and steer its agents. From your phone you can: - see your connected machines and their live agent sessions, - start a new session (pick a machine, a project, and an agent) and send tasks, - watch activity stream in real time, - approve or deny the agent's permission requests, - stop a run, and review the files it changed. **Your code never leaves your machine.** The cloud routes structured control messages and stores only metadata (labels and ids) — never your files, paths, credentials, or model keys. Supported agents (bring your own): **[OpenCode](https://opencode.ai)**, **[Claude Code](https://claude.com/claude-code)**, and **Codex**. roamux does not implement its own agent — it drives yours through a swappable `HarnessAdapter`. ## Prerequisites roamux **drives an agent you already run locally** — it does not ship or proxy a model. So before you start, install and sign in to **one** of the supported agent CLIs on the machine you want to control (this is where your model access and auth live — nothing leaves the box): | Agent | Install | Sign in | | --- | --- | --- | | **[OpenCode](https://opencode.ai)** | `curl -fsSL https://opencode.ai/install \| bash` | `opencode auth login` | | **[Claude Code](https://claude.com/claude-code)** | `curl -fsSL https://claude.ai/install.sh \| bash` | `claude` (run once, complete the login) | | **Codex** | `npm install -g @openai/codex` | `codex login` | You only need one. If the agent isn't installed or signed in, `roamux host` refuses to start and prints the exact commands to fix it. ## Quick start **On the machine you want to control** (macOS or Linux): ```sh # 1. Install the host CLI curl -fsSL https://remote.phyra.ai/install.sh | sh # 2. Link it to your account (opens a code — approve it in your browser) roamux login # 3. Start it in the project you want the agent to work on, picking the agent. # AGENT_ADAPTER defaults to `opencode` — set it for Claude Code or Codex. cd ~/your/project AGENT_ADAPTER=claude-code roamux host # or opencode | codex ``` Then open **[the web app](https://remote.phyra.ai)** on your phone or browser, sign in, pick your machine → **New Session** → choose the project + agent + a task → **Start**, and watch it run. > A host serves **one** agent — whichever `AGENT_ADAPTER` you launched it with. > To offer several, run one host per agent. > **File edits:** the agent auto-accepts file edits so it can actually do the > work (it still won't run destructive shell commands unattended). Point it at a > project you're comfortable letting it change — a git repo is ideal. > **Keep it running in the background** (survives closing the terminal / logout): > `roamux service install` ### CLI | Command | What it does | | --- | --- | | `roamux login` | Link this machine to your account (device authorization) | | `roamux host` | Start the host daemon and serve your agents | | `roamux service install` | Install the host as a background service (launchd / systemd) | | `roamux service status` / `uninstall` | Manage the background service | | `roamux help` · `roamux version` | Usage / version | Configure via env: `AGENT_ADAPTER=opencode|claude-code|codex` picks the agent (default `opencode`), `DEFAULT_PROJECT_PATH=` sets the project (default: the current directory), `HOST_NAME=` labels the machine. ## How it works ``` Phone / Browser ─▶ roamux Cloud (web + API) your machine │ │ auth · host & session registry host daemon ─▶ agent ─▶ model │ │ mints scoped realtime tokens ▲ └─────────────── realtime transport (Ably) ─────────────────────┘ (host dials OUT) ``` Three boundaries carry the whole design: - **Protocol** (`packages/protocol`) — every message on the wire is a **versioned, Zod-validated** envelope. No raw internal objects, ever. - **Transport** — how bytes move, behind one interface: a local WebSocket relay for development, and [Ably](https://ably.com) in production. Swappable. - **HarnessAdapter** (`packages/agent-adapters`) — how a runtime is driven. Agent-specific code lives *only* inside its adapter; the rest of the system speaks one normalized event vocabulary. **Security invariants** (enforced in code and tests): - the agent runtime binds to **localhost only**; - the **host dials out** — nothing local is exposed via an inbound port; - routing is authenticated and **scoped per user**, so one account can never reach another's machines; - there is **no arbitrary remote shell** — clients send a small set of explicit, validated commands, never shell strings or filesystem paths; - repos, credentials, env vars, and model keys **never cross the wire**. Full write-ups, with diagrams, in [docs/architecture.md](docs/architecture.md) (the as-built local slice) and [docs/beta-architecture.md](docs/beta-architecture.md) (the multi-host, hosted design of record). ## Use it from an AI client (MCP) Besides the web app, roamux exposes its control surface as an **MCP server** — so you can drive your hosts straight from an MCP-capable chat client (Claude desktop/mobile, ChatGPT, …). The chat app becomes the UI; roamux routes the commands to the agent running on your machine. It's **additive** — the web app is unchanged, and an MCP client can do only what a browser session can (the same small, validated command set). ``` Claude / ChatGPT ──▶ https://remote.phyra.ai/api/mcp ──▶ Ably ──▶ your host ──▶ agent (MCP client) (roamux MCP server, OAuth) (scoped per user) ``` ### Step by step **Before you start:** you need a roamux account and **a host already linked and running** — do the [Quick start](#quick-start) first (`roamux login` + `roamux host`). Sign in to the MCP client with the **same account** that linked the host, or the client will see none of your machines. **1. Get your host id.** Easiest: just ask the client *"list my roamux hosts"* — the `roamux_list_hosts` tool returns each machine's id + status. (Or copy it from your machines list at **[remote.phyra.ai](https://remote.phyra.ai)**.) **2. Add roamux as a connector in your client:** - **Claude** (Settings → **Connectors** → **Add custom connector**): - URL: **`https://remote.phyra.ai/api/mcp`** - Save. Claude opens a sign-in window — **log in with the same roamux (GitHub) account** as your host. No keys to paste. - **ChatGPT** (Settings → **Connectors** → **Create** / add MCP server): - URL: **`https://remote.phyra.ai/api/mcp`**, auth: **OAuth** → sign in. - Any other MCP client: add a **remote/HTTP MCP server** at that URL; it auto-discovers the OAuth flow. **3. Chat to drive your agent.** In a new conversation, try — pasting your real host id: ```text Using roamux, list the projects on host . ``` then: ```text Start a claude-code session on that host in the roamux-demo project, and have it create a file hello.txt that says "hello from Claude". Then show me the activity. ``` The agent runs on **your** machine and writes the file there — you're steering it from the chat app. Follow up with "what's the latest activity?" to watch a long run, or "stop that session" to halt it. > **Nothing came back / "no projects"?** Almost always an account mismatch — the > client is signed into a different roamux account than the one that linked the > host. Confirm the host appears in your machines list at remote.phyra.ai **under > the same account you used in the client**, and that the host is running. ### The tools | Tool | Does | | --- | --- | | `roamux_list_hosts` | your linked machines + their ids/status (remote server only) | | `roamux_list_sessions` | sessions on a host | | `roamux_list_projects` | approved projects + installed agents (valid `start_session` inputs) | | `roamux_start_session` | start a session for a project + agent | | `roamux_send_prompt` | send an instruction to a session | | `roamux_get_activity` | poll a session's recent activity | | `roamux_stop_session` | stop a session | | `roamux_respond_permission` | allow/deny a permission the agent is waiting on | There is **no generic "run anything" tool** — the surface mirrors roamux's closed command set. A local **stdio** variant (for Claude Desktop on the same machine) also ships; see [apps/mcp/README.md](apps/mcp/README.md). Self-hosting the remote server: see [DEPLOY.md](DEPLOY.md) + [apps/mcp/REMOTE-DESIGN.md](apps/mcp/REMOTE-DESIGN.md). ## Repository layout ``` apps/ host/ the daemon + `roamux` CLI. Runs on the user's machine, dials out, owns sessions. Compiles to a single binary. relay/ local-dev WebSocket router (not used in production — Ably replaces it). web/ Next.js — the mobile-first control UI + API + auth. Deploys to Vercel. packages/ protocol/ Zod envelopes, commands/events, the Transport interface, channels. agent-adapters/ HarnessAdapter + OpenCode / Claude Code / Codex + a mock for tests. db/ Postgres schema, migration runner, typed repositories. docs/ architecture and design docs. ``` ## Development You do **not** need any cloud accounts to develop. The fastest path: ```sh bun install bun run dev # relay + host (mock agent) + web at http://localhost:3000 ``` Full guide — local database, real agents, running the test suite — in **[CONTRIBUTING.md](CONTRIBUTING.md)**. Before opening a PR: ```sh bun run check # typecheck + lint + tests — must be green ``` ## Tech stack TypeScript (strict) · [Bun](https://bun.sh) · [Next.js](https://nextjs.org) · [Zod](https://zod.dev) · [Ably](https://ably.com) (realtime) · [Supabase](https://supabase.com) (Postgres + auth) · deployed on [Vercel](https://vercel.com). ## Contributing Contributions are welcome. Start with **[CONTRIBUTING.md](CONTRIBUTING.md)** for setup, and [CLAUDE.md](CLAUDE.md) (aliased `AGENTS.md`) for the working agreement every contributor — human or AI coding agent — follows. Keep `bun run check` green and never weaken a security invariant silently. ## License [MIT](LICENSE)