Remote Collab Agents

You have 3 machines and Claude Code on each. How do they work together?

This project gives AI coding agents the ability to reach across machines — executing commands, syncing files, and monitoring each other — while humans stay in control of trust-critical decisions.

Born from real deployment across 3 machines (macOS + Ubuntu). Every design decision and troubleshooting entry reflects an actual challenge encountered.

Demo

# Agent on your MacBook delegates a GPU task to a remote workstation
$ remote-exec workstation-a "nvidia-smi"
[remote] workstation-a (alice@100.64.0.1:22) $ nvidia-smi
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 550.54    Driver Version: 550.54    CUDA Version: 12.4           |
| GPU  Name        Persistence-M | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
|   0  GeForce RTX 3060   Off    | 00000000:01:00.0  On |                  N/A |
| 30%   45C    P8    15W / 170W  |    512MiB / 12288MiB |      0%      Default |
+-----------------------------------------------------------------------------+

# Launch a training job in the background — survives SSH disconnects
$ remote-exec workstation-a --bg "python3 train.py --epochs 100"
[bg] Started task train_20260325_143022 on workstation-a (PID: 48291)

# Check all machines at once
$ remote-exec all "uptime"
[remote] workstation-a: 14:30:22 up 12 days, load average: 0.15, 0.10, 0.08
[remote] workstation-b: 14:30:23 up 3 days,  load average: 0.42, 0.38, 0.35
[remote] macbook:       14:30:22 up 1 day,   load average: 1.20, 1.15, 1.10

# Sync files between machines
$ remote-sync push workstation-a ./model.pt /home/alice/Desktop/Share/
[rsync] Transferred model.pt → workstation-a (256.3 MB, 12.8 MB/s)

# Delegate complex work to a remote machine's AI agent
$ remote-agent workstation-a claude -p "explain the main function in server.py"
[INFO] Agent: claude on workstation-a
[INFO] Working dir: ~
The main function in server.py initializes a Flask application...

# Ask a remote Codex to refactor code
$ remote-agent workstation-b codex exec "add input validation to api.py"
[INFO] Agent: codex on workstation-b
Applied 3 changes to api.py

# Check which agents are available across the mesh
$ remote-agent all --info
[workstation-a] Claude Code: v2.1.83, Codex CLI: v0.116.0, Node: v24.14.0
[workstation-b] Claude Code: v2.1.39, Codex CLI: v0.116.0, Node: v22.22.1

# Full health diagnostics across the mesh
$ remote-collab-doctor
[doctor] Checking 17 items across 3 machines...
  ✓ SSH connectivity      3/3
  ✓ Tailscale mesh        3/3
  ✓ Scripts deployed      3/3
  ✓ Syncthing sync        3/3
  Result: 17/17 PASS

Why This Exists

Most multi-agent frameworks focus on orchestrating LLM calls. This one focuses on something different: giving agents physical reach across your machines.

What others do	What this does
Agent A calls Agent B's API	Agent A invokes Agent B's CLI on Machine B
Shared memory / message passing	Shared filesystem via rsync + Syncthing
Central orchestrator	Peer-to-peer mesh — every machine is equal
Simulated environments	Real SSH on real machines

How It Works

┌──────────────────────┐     Tailscale VPN      ┌──────────────────────┐
│   Workstation A       │◄─────────────────────►│   Workstation B       │
│   ┌──────────────┐   │      SSH + rsync       │   ┌──────────────┐   │
│   │ Claude Code  │   │                        │   │ Claude Code  │   │                        │   │ Claude Code  │   │
│   │   Agent      │───┼── remote-agent ───────►│   │   Agent      │   │
│   └──────────────┘   │                        │   └──────────────┘   │
│   ┌──────────────┐   │                        │                      │
│   │ Human (SSH)  │   │                        │                      │
│   └──────────────┘   │                        │                      │
└──────────────────────┘                        └──────────────────────┘
          ▲                                               ▲
          │              Syncthing (continuous)            │
          ▼                                               ▼
┌──────────────────────┐                                  │
│   MacBook             │◄────────────────────────────────┘
│   ┌──────────────┐   │
│   │ Claude Code  │   │
│   │   Agent      │   │
│   └──────────────┘   │
└──────────────────────┘

Each machine runs its own AI agent. Agents can:

Delegate tasks — "Run this training on the GPU workstation"
Share files — Push data to shared folders, pull results back
Monitor each other — Health checks, background task status, sync state
Evolve together — One agent improves a skill, deploys updates to all others

Features

Remote agent invocation — invoke Claude Code or Codex CLI on any machine via remote-agent
Cross-machine command execution — foreground, background, or broadcast to all
Background task management — PID-verified, survives SSH disconnects, with log tailing
Bidirectional file sync — rsync for on-demand, Syncthing for continuous
Per-host environment bootstrapping — auto-handles nvm, PATH, install-path differences across machines
Three-tier safety model — safe / needs-confirmation / dangerous command classification
Shell injection prevention — metacharacters always trigger human review
Distributed diagnostics — doctor checks SSH, Tailscale, Syncthing, scripts, PATH across all machines
Automated setup wizard — 11-step process: key generation, config, deployment, mesh establishment
macOS + Linux — works on bash 3.2 (macOS) and 4+ (Linux), handles GNU/BSD differences

Quick Start

Prerequisites

2+ machines with Tailscale installed
SSH server enabled on each machine
Bash 3.2+ (macOS compatible)
Syncthing (optional, for continuous sync)

Install

git clone https://github.com/PluteW/remote-collab-agents.git
cd remote-collab-agents

# Deploy skills to Claude Code (on each machine)
mkdir -p ~/.claude/skills/remote-collab/scripts
cp scripts/* ~/.claude/skills/remote-collab/scripts/
cp skills/* ~/.claude/skills/remote-collab/

# Run the setup wizard
bash scripts/setup-ssh-keys.sh

The wizard handles SSH keys, config files, script deployment, cross-machine mesh, Syncthing discovery, symlinks, and health checks — all in one run.

See docs/deployment-guide.md for the full step-by-step guide.

Safety Model

Not all commands are equal. The system classifies every command before execution:

Tier	Examples	Behavior
Safe	`ls`, `hostname`, `df`, `nvidia-smi`	Execute directly
Needs Confirmation	`python3 train.py`, `pip install`	Ask human first
Dangerous	`rm -rf`, `sudo`, `reboot`	Explicit warning + confirmation

Shell metacharacters (;, &&, |, $()) always require confirmation — preventing injection attacks like echo $(rm -rf /) from sneaking through as "safe".

Technology Stack

Layer	Technology	Role
Network	Tailscale	Mesh VPN, NAT traversal, encryption
Transport	SSH	Authenticated command execution
File Sync	rsync + Syncthing	On-demand + continuous sync
Agent	Claude Code	AI coding assistant with skill system
Config	Bash (restricted parser)	Simple, no YAML deps

Lessons from Real Deployment

Deploying across 3 machines revealed challenges that require human-agent collaboration:

Challenge	Solution
First SSH auth needs password	Human runs `ssh-copy-id` once
Missing `openssh-server`	Human installs: `sudo apt install openssh-server`
Different usernames per machine	Config explicitly specifies each: `HOSTS_x="bob@host:22"`
`authorized_keys` corruption	Use `ssh-copy-id`, never manual paste
Syncthing needs Tailscale IPs	Address must be `tcp://100.64.x.x:22000`, not hostname
macOS bash 3.2 limitations	Scripts handle: no `mapfile`, no `flock`, no `grep -oP`
Cross-machine SSH mesh	Setup script auto-generates keys and distributes

See docs/reference.md for 10 documented issues with solutions.

Project Structure

remote-collab-agents/
├── scripts/
│   ├── common.sh              # Shared library: config, safety, host resolution
│   ├── remote-exec.sh         # Remote execution (fg/bg/broadcast)
│   ├── remote-agent.sh        # Remote agent invocation (Claude Code / Codex)
│   ├── remote-sync.sh         # rsync + Syncthing management
│   ├── remote-wrapper.sh      # Background task lifecycle
│   ├── doctor.sh              # Distributed health diagnostics
│   └── setup-ssh-keys.sh      # Setup wizard (11 steps)
├── skills/
│   ├── remote-exec.md         # Claude Code skill: remote execution
│   ├── remote-agent.md        # Claude Code skill: remote agent invocation
│   └── remote-sync.md         # Claude Code skill: file sync
├── docs/
│   ├── design.md              # Architecture design
│   ├── reference.md           # Operations reference + troubleshooting
│   └── deployment-guide.md    # Step-by-step deployment guide
└── config/
    └── hosts.conf.example     # Configuration template

Contributing

This project emerged from hands-on deployment experience. Contributions welcome:

New machine types — tested on macOS + Ubuntu; Windows WSL, Raspberry Pi, cloud VMs untested
New agents — currently built for Claude Code; adapting for Codex, Gemini Code Assist, etc.
Security hardening — the trust model can always be improved
Documentation — deployment guides for different environments

Open an issue or submit a PR.

License

MIT

🇨🇳 中文版 / Chinese Version