Protean

An experiment in distributed and auto-evolving AI agents — letting a single agent auto-update its own code and spread across a network of machines instead of being confined to one.

---

The idea

Today's AI agents have fixed tools, fixed capabilities, and are bound to a single process on a single machine. Protean explores what happens when you remove these constraints: an agent that controls its own code and exists as a network, migrating compute where it's needed, gaining capabilities by adding hardware, and persisting as a git repository that any machine can resume.

The agent is its git repository. Every machine in the network runs the same codebase. One is elected master (runs the LLM brain), the others sync state and provide access to their hardware and tools. Push a commit and the entire network updates within 30 seconds.

---

What can it do

• Span multiple machines. Add a Raspberry Pi with a webcam — now it can see. Add a cloud GPU — now it can train models. Add a VPS — now it has a public IP. One command per device. In our tests, we've seen the agent create its own AWS instances and spread to them, then figure out they don't have enough RAM and scale them.
• Build its own tools. Need a capability that doesn't exist? The agent writes an MCP tool, drops it in tools/, and restarts itself. No human release cycle. The webcam tool, in this repo, was built like this.
• Pick its own model. The agent rewrites its own harness to use whatever LLM makes sense — local Llama for cheap tasks, Claude Opus for hard ones, a new model the day it drops.
• Survive anything. If the master goes down, another machine takes over. If all machines go offline, the agent hibernates as a git repo and resumes when any one comes back.
• Run remote terminals. Open shells on any machine in the network, execute commands, stream output — all over encrypted P2P.
• Transfer files across machines. Move data between nodes without exposing ports or configuring anything.
• Tunnel ports. Forward a port from one machine to another through the P2P mesh — expose a local dev server to a cloud node, or vice versa.
• Stream live video/audio. Pipe a webcam or mic from one machine to the agent in real time over low-latency P2P streams.
• Self-heal. Bad commit breaks the runtime? Safe-mode walks back through git history commit-by-commit until it finds one that works.

---

Web client

A serverless viewer is available at protean.interagentic.inc or as a portable HTML file.

It is a single static HTML file — no backend, no accounts, no telemetry. The page derives encryption keys from the agent's git URL entirely in-browser (crypto.subtle), connects to Streambin.xyz for real-time e2e-encrypted event streaming, and renders the conversation locally. Nothing leaves the browser except encrypted Streambin.xyz traffic. You can download the file and open it from disk; it is fully portable.

---

How it works

┌─────────────────────────────────────────────────────────────┐
│                        Bootstrap                            │
│   Setup → Identity → Register → Supervise runtime           │
│                         │                                   │
│                    ┌────┴────┐                              │
│                    │  main   │◄── crash loop ──► safe-mode  │
│                    └────┬────┘                              │
└─────────────────────────┼───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
     ┌────┴─────┐   ┌────┴─────┐   ┌─────┴─────┐
     │Hyperswarm│   │  CRDT    │   │  Claude   │
     │   P2P    │   │  State   │   │  Agent    │
     │(in-proc) │   │  (Yjs)   │   │ (Master)  │
     └──────────┘   └──────────┘   └───────────┘

• P2P: Hyperswarm — DHT discovery, Noise encryption, NAT traversal. Three-layer discovery: peer cache (instant) → ntfy.sh hints (1–3s) → DHT (fallback).
• State: Yjs CRDTs synced over P2P. No consensus protocol — eventual consistency mediated by an AI that reasons about conflicts.
• Election: Deterministic lowest-ID-wins among connected peers.
• Auto-update: Every machine polls origin/main every 30s. New commits trigger automatic restart.
• Crash recovery: 3 consecutive crashes → safe-mode → diagnostics → pull latest → retry.

For a full technical walkthrough, see docs/UNDER_THE_HOOD.md.

---

Quickstart

Prerequisites: Node.js v20+, Git, an Anthropic API key.

git clone https://github.com/smarcombes/protean && cd protean
npm install && npm start
# Select "Create agent" to create a Git repo and define your agent's name

On first run, bootstrap prompts you to create a new agent or join an existing one.

Add a machine

On any other device:

git clone https://github.com/smarcombes/protean && cd protean
npm install && npm start
# Choose "Join" and paste the agent's git clone URL

The machine registers, connects via P2P, and appears in the network within seconds.

---

License

MIT