# remote-agents

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/47-ronn/tunshell_mcp_agents  
**GitHub Stars:** 2  
**npm Downloads (last month):** 1437  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/remote-agents

## Description
Control fleets of remote machines via AI agents: exec, files, git, fleet ops, map/reduce.

## Tools
Capabilities this server exposes over MCP:

- **exec** — Run a shell command (locally or on a remote agent via `agent_id`)
- **read_file** — File operations (write requires Edit/Bypass)
- **get_info** — Inspect / change an agent's mode at runtime
- **git_status** — Git operations
- **schedule_add** — Cron-style tasks on a host
- **task_dispatch** — Autonomous AI tasks run with the host's own credentials
- **session_list** — Browse the host's AI-chat history (claude / opencode / codex / cline / roo / kilo / zed / cursor / gemini / qwen / goose / continue); `session_get` fetches a transcript or a window around one message
- **session_search** — Full-text search over the host's AI-chat history — a local Tantivy (BM25) index of every provider transcript, returning ranked cited snippets with `session_id` + message position (follow up with `session_get { around_seq }` for the context)
- **list_agents** — List agents connected to the relay room
- **fleet_exec** — Run an operation across the fleet — `target = all \
- **fleet_session_search** — Search the AI-chat history across the whole fleet: every matched host queries its local index, hits merge by score with host labels
- **file_search** — Find files on a host, and move a file host→host (UDP, SHA-256 verified)
- **sync_dir** — Sync a directory tree host→host (rsync-like): only changed/new files are sent, with optional `delete`, `checksum`, and `dry_run
- **tunnel_start** — Expose a host's local port at a public `*.trycloudflare.com` URL via a Cloudflare quick tunnel (`cloudflared` auto-downloaded; Edit/Bypass)
- **mapreduce** — Distributed map/reduce over the fleet (shell map/reduce functions)

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "remote-agents": {
    "command": "npx",
    "args": ["-y","remote-agents"]
  }
}
```

## Documentation

## What remote-agents does

remote-agents provides one Rust binary that can run as a headless peer, an MCP stdio server, or an installed background service. The MCP mode connects a local AI host to a relay room and makes connected machines available through agent tools. Remote hosts can execute commands, inspect or modify files according to their safety mode, work with Git, schedule cron-style tasks, and run delegated AI tasks using their own credentials.

Fleet features treat multiple peers as a single operational group. Operations can target every connected host, or be selected by tags or operating-system family. Distributed MapReduce partitions work across the fleet, runs shell-based map and reduce functions, and supports retries per partition. Hosts can also search locally indexed AI-chat transcripts, while fleet search merges ranked results from multiple machines.

## How it works

Agents connect outbound to a relay using a shared room and token. The relay carries control messages and UDP signaling, while payloads are end-to-end encrypted with AES-GCM-256. A Cloudflare Worker relay and a self-hosted Rust WebSocket relay are supported. Bulk file transfers try a direct UDP/QUIC channel with hole punching and fall back to the relay when necessary.

The network is flat: every node joins as an equal peer and can dispatch work or accept commands by default. A `run` process is intended for a headless host, while `mcp` adds the MCP interface for a local AI host; `hybrid` is an alias for `mcp`. Adding `--no-agent` makes a node visible and able to dispatch work without executing commands from other peers.

Hosts can use `plan`, `edit`, `bypass`, or `disabled` safety modes. Path and command allow-lists and deny-lists provide additional controls. Edit and bypass authorization is required for operations that write files or expose a local port through a Cloudflare quick tunnel.

## Setup and configuration

Install a platform binary through npm, run it on demand with `npx`, build the workspace with Cargo, or install the MCP crate from source. Prebuilt binaries are also published for macOS, Linux, and Windows. A typical deployment keeps target machines online with `remote-agents run` or the `install` command, while a workstation starts `remote-agents mcp` for an AI session.

Connection settings can be supplied as command-line flags, `REMOTE_AGENTS_*` environment variables, or `config.toml`, in that precedence order. The main connection values are the relay URL, room, token, node name, tags, and optional send-only mode. The public relay can be used for an initial setup, or operators can deploy the Rust relay and configure its bind address, authentication, connection limits, and idle timeout.

Installed services use a systemd user service on Linux or a launchd LaunchAgent on macOS. A persistent service and an MCP session should not use the same agent identity simultaneously because the relay keys peers by that identity.

## Tools and capabilities

- Execute shell commands locally or on a selected agent.
- Read and write files subject to the active safety mode.
- Inspect or change an agent's runtime mode.
- Check Git state and schedule cron-style host tasks.
- Delegate autonomous AI tasks to a host using its credentials.
- List peers and run commands or operations across the fleet.
- Search and retrieve provider chat transcripts, including context around a message.
- Transfer files between hosts with SHA-256 verification and synchronize directory trees with options such as deletion, checksums, and dry runs.
- Start a Cloudflare quick tunnel for a host-local port.
- Distribute shell-based map and reduce work across fleet members.

## Limitations and notes

The MCP node remains connected only while its AI host keeps the process running; use an installed `run` service for continuous availability. Every node accepts commands by default unless `--no-agent` is enabled, so safety modes and command or path restrictions should be configured for the intended trust model. Direct peer-to-peer transfer depends on network conditions and uses relay fallback when UDP hole punching cannot succeed. Room membership depends on the room and token combination, and a mismatched token places a peer in a separate room.

_Full upstream README: https://allmcps.com/mcp/remote-agents/readme_