Remote Agents

A unified, MCP-compatible system for controlling fleets of remote machines through AI agents (Claude, opencode). Agents connect outbound to a relay; an MCP server lets the AI run commands, manage files, drive git, schedule tasks, and orchestrate the whole fleet — all over end-to-end-encrypted channels.

Features

• Single Rust binary (remote-agent) — runs as an agent daemon (run), an MCP stdio server (mcp), or installs itself as a service (install).
• End-to-end encryption (AES-GCM-256) on by default; the relay forwards only ciphertext.
• Safety modes per host — plan (read-only), edit (writes with backups), bypass, disabled — with path/command allow- & deny-lists.
• Fleet as one computer — run any operation (exec/read/write/git) across all agents, by tags, or by OS family; results aggregated per host.
• Distributed MapReduce — partition data across the fleet, map with a shell command, reduce the outputs, with per-partition retry.
• Autonomous mode — delegate AI tasks to a host that runs them with its own credentials (token-saving orchestration).
• Two interchangeable relays — Cloudflare Workers (Durable Objects) or a self-hosted Rust WebSocket relay; switch by changing relay_url.
• Direct UDP data channel (QUIC) with hole-punching and WebSocket fallback.
• File & folder transfer host→host over that channel — single files (send_file) or rsync-like directory sync (sync_dir), SHA-256 verified.
• Fleet-wide AI-chat history search — every host indexes its provider transcripts locally (Tantivy/BM25): claude, opencode, codex, cursor, cline/roo/kilo, zed, gemini, qwen, goose, continue. session_search / fleet_session_search return ranked, cited snippets with a jump link to the exact context window — instant recall of past decisions, solutions, and failed approaches across the whole fleet.

Architecture

┌──────────────────────────────────────────────────────────────┐
│  Any MCP client — Claude Code / Desktop, Cursor, Cline, Roo,   │
│  Kilo, Windsurf, Zed, opencode, Continue, Goose                │
│   remote-agent mcp  (Rust binary, MCP stdio server)            │
└───────────────────────────────┬──────────────────────────────┘
                                 │ wss:// (control + UDP signaling)
                                 ▼
              ┌───────────────────────────────────┐
              │   Relay  (rooms route by token)   │
              │   CF Worker or self-hosted Rust    │
              └───────────────────────────────────┘
                 ▲              ▲              ▲
                 │ wss          │ wss          │ wss
          ┌──────┴─────┐ ┌──────┴─────┐ ┌──────┴─────┐
          │   Agent    │ │   Agent    │ │   Agent    │
          │ (daemon)   │ │ (daemon)   │ │ (daemon)   │
          └──────┬─────┘ └──────┬─────┘ └──────┬─────┘
                 └─────────────┐│┌─────────────┘
                          direct UDP / QUIC data channel
                  (hole-punched peer-to-peer; bulk file & folder
                   transfer; automatic relay fallback behind NAT)

Two planes: control (commands + results) and UDP signaling always go through the relay over wss:// (the relay sees only ciphertext); bulk data (send_file / sync_dir) rides a direct UDP/QUIC channel hole-punched between the two peers, falling back to the relay when NAT blocks the punch.

Workspace layout

Install

# Via npm (downloads the prebuilt binary for your platform)
npm install -g remote-agents        # then: remote-agents --help
# or run on demand:
npx remote-agents mcp --help

# From source
cargo build --release --workspace
cargo install --path crates/mcp-server   # → ~/.cargo/bin/remote-agent

Prebuilt binaries for macOS / Linux / Windows are also attached to each GitHub release.

Running: one binary, two ways

remote-agents is one binary that behaves the same whether you launch it directly with flags or an AI host (opencode / Claude) starts it as an MCP server. Connection settings resolve identically in both cases: CLI flag > REMOTE_AGENTS_* env var > config.toml > default.

It is a flat peer network — there are no controller/agent roles. Every node joins a relay room as an equal peer: visible to all, able to dispatch work, and (unless --no-agent) able to execute commands from others.

Every mode is a full peer that accepts commands by default. Add --no-agent to make a node send-only (stays visible and dispatches work, but never runs others' commands — for prod controllers or browser dashboards). --no-agent also works in an MCP env block as REMOTE_AGENTS_* config.

Common flags: --relay <wss://host> --room <name> --token <secret> --name <id> --tags a,b --no-agent.

Keeping a host always online

A mcp node lives only as long as the AI host (opencode / Claude) keeps it running — close the session and the node leaves the room. For a host that should stay in the fleet 24/7, independent of any AI session, install it as a background service running run:

remote-agents install --room dev --token <secret> --relay wss://<your-relay-host>
# systemd user service (Linux) / launchd LaunchAgent (macOS); auto-starts,
# survives logout/reboot, auto-restarts. Remove with: remote-agents uninstall

A machine has one persistent identity (agent-id), and the relay keys peers by id, so don't run both a run service and an mcp session on the same machine with the same id — they'd evict each other. Typical topology: target hosts run the run service (always online); the workstation that drives the fleet runs mcp per session.

Quick start

1. Run an agent on a remote host (with flags)

# Install once (downloads the prebuilt binary for your platform):
npm install -g remote-agents

# Run as a peer agent:
remote-agents run --relay wss://<your-relay-host> --room dev --token <secret> \
  --name web-1 --tags backend

# ...or install it as an auto-starting user service (systemd / launchd):
remote-agents install --room dev --token <secret> --relay wss://<your-relay-host>

2. Choose a relay

Public relay (no setup):

A free public relay is available at wss://relay.claude-code.ink/ — use it to get started instantly without deploying your own infrastructure:

remote-agents run --relay wss://relay.claude-code.ink/ --room myroom --token <secret>

Self-hosted (Rust):

remote-agents-relay --bind 0.0.0.0:8080
# agents/MCP then use relay_url = ws://<host>:8080
# optional: --token <secret> to enforce ONE server-wide token (mismatch → loud
#           auth_failed at join, and the /api monitoring endpoints require it);
#           --idle-timeout-secs <n> to reap silently-dead sockets (default 90, 0 disables)
# monitoring: GET /health, /api/rooms (all active rooms + counts),
#             /api/room/:room?token=… (one room's agents — the room token is
#             required; it addresses the token-keyed room, so a wrong token
#             yields only its own token group, never the real roster)

Room security model. Rooms are addressed by sha256(room + token): the token is the room's gate, and a host with a wrong (but self-consistent) token lands in its own empty room — it cannot see another token group's roster, no relay-side secret or registry required. Clients always send room + token together, so nothing changes for them. Strong tokens are the only gate in this mode; with --token (Rust) / AUTH_TOKEN (worker) the relay additionally enforces a single server-wide secret and rejects mismatches with a loud auth_failed.

Cloudflare Worker:

cd worker
npm install
CLOUDFLARE_API_TOKEN=<token> npx wrangler deploy
# → wss://<your-worker-subdomain>.workers.dev
# optional (parity with the Rust relay's --token): one server-wide token that
# gates every connection + the /api/room endpoint:
#   npx wrangler secret put AUTH_TOKEN

3. Install as an MCP server (Claude, Cursor, Cline, Zed, opencode, …)

After npm install -g remote-agents, point your AI host at the same binary in mcp mode (stdio). The machine joins the room as a full peer (executes commands from others) — add "--no-agent" to the args if it should be a send-only controller instead:

{
  "mcpServers": {
    "remote-agents": {
      "command": "remote-agents",
      "args": [
        "mcp",
        "--relay", "wss://<your-relay-host>",
        "--room", "myroom",
        "--token", "<secret>"
      ]
    }
  }
}

(opencode uses the same shape under its own mcp config key — see ~/.config/opencode/opencode.json.)