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.

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