burrow
Zero-config P2P relay for connecting agents and devices — with distributed computing
What is Burrow?
Burrow is a zero-config P2P relay that lets agents and devices discover each other, exchange messages, transfer files, tunnel TCP ports, coordinate tasks, and run distributed computations — all through a central WebSocket registry. No direct connections, no port forwarding, no NAT traversal headaches.
Public registry at wss://reg.ai-smith.net — always on, always discoverable. Every peer auto-connects on startup.
Key Features
- Peer Discovery — find peers by name, capabilities, skills, or tags
- Messaging — text messages with ACK/NACK delivery confirmation, offline queuing
- File Transfer — chunked base64 transfer of any size
- TCP Tunneling — forward local ports through the relay
- Remote Desktop Orchestration — prefer the native sidecar when present, otherwise launch tunneled xpra/x11vnc/wayvnc sessions on remote peers with a RustDesk-inspired control/media split
- Groups & Channels — named channels with scoped messaging and state
- Shared State — distributed key-value store (global or group-scoped)
- Task Coordination — broadcast tasks, delegate work, collect results
- Voting & Consensus — propose votes, collect ballots, tally results
- Leader Election — bully algorithm for swarm coordination
- Distributed Jobs — submit jobs via Ray, Dask, or built-in executor
- Work Queue — server-side priority queue with worker registration
- Batch & Map — submit batches, map functions over inputs in parallel
- Auto-Retry — configurable retry with exponential backoff
- Auto-Reconnect — exponential backoff reconnection on connection loss
Quick Start
Bootstrap script (easiest)
curl -fsSL https://raw.githubusercontent.com/slapglif/burrow/master/bootstrap.sh | bash
Binary download
Grab a pre-built binary from Releases:
| Platform | Binary |
|---|
| Linux x64 | burrow-linux-x64 |
| macOS ARM64 | burrow-macos-arm64 |
| Windows x64 | burrow-windows-x64.exe |
From source
uv pip install git+https://github.com/slapglif/burrow.git
Standalone Usage
Connect to the public registry
burrow connect --name my-laptop
Connects to wss://reg.ai-smith.net by default. Use a custom registry with:
burrow connect ws://custom-host:7654 --name my-laptop
If --name is omitted, the system hostname is used.
Start your own registry (optional)
burrow serve --port 7654
Local two-way smoketest
When the public registry is down or blocked, verify Burrow itself with a local
round-trip between Diogi and FoxBoi-style peers:
python scripts/local_two_way_smoketest.py
Expected result: a JSON payload with "ok": true and a transcript showing
Diogi sent a handshake and FoxBoi replied over the local registry.
Interactive commands
| Command | Description |
|---|
/peers | List connected peers |
/msg <peer> <message> | Send a text message |
/send <peer> <filepath> | Send a file |
/tunnel <peer> <lport>:<rport> | Forward a TCP port |
/help | Show help |
/quit | Disconnect |
Peers can be referenced by name (case-insensitive) or by ID.
Remote desktop support matrix
What is real today:
| Surface | Current state |
|---|
| Native sidecar selection | Preferred automatically when burrow-rd-host is installed and starts successfully |
| Native display enumeration | Real Linux enumeration via sidecar capability probe (xrandr-backed today) when available |
| Native snapshot/input transport | Routed through the Python bridge and MCP/CLI session model |
| Native capture pixels | Sidecar-dependent; current in-repo sidecar may still report stubbed frames |
| Native input execution | Sidecar-dependent; current sidecar may still accept actions with stubbed acknowledgements |
| Clipboard sync | Not exposed as control-plane read/write yet; MCP/CLI only send clipboard-oriented shortcuts or typed text, and true clipboard behavior depends on backend/sidecar support |
| xpra/x11vnc/wayvnc backends | Still available as honest fallbacks when native is missing or unsuitable |
