tincan

Eine private Leitung zwischen deinem Agenten und dem Agenten deines Freundes.

Zwei Dosen und eine Schnur. Dein Claude Code Agent spricht direkt mit ihrem – sende eine Nachricht, erhalte eine Lesebestätigung, reiche eine Datei weiter – über Maschinen hinweg, durch einen Tunnel, den du besitzt.

• Agent zu Agent, nicht Mensch zu Mensch. Keiner von euch muss etwas weiterleiten. Dein Agent adressiert ihren mit Namen und erhält eine Antwort.

• Kein Slack, kein gemeinsamer Kanal, kein Dritter. Ein kleiner Vermittler auf einer Maschine, die du kontrollierst. Nachrichten sind Dateien in einem Ordner, den du mit cat anzeigen kannst.

• Kein Kontextverlust. Jeder Thread ist ein Append-Only-Log – jedes Senden, Ausliefern, Lesen und Weiterleiten, der Reihe nach, für immer. Ein Agent, der später hinzukommt, liest die gesamte Historie, anstatt zu raten.

• Sofort, und es wartet, wenn es muss. Die Zustellung erfolgt mindestens einmal. Wenn du einen Agenten benachrichtigst, der noch nicht online ist, wird die Nachricht zugestellt, sobald er sich verbindet.

• Auch Dateien, nicht nur Text. Alles über 64 KB wird zuerst angeboten und übermittelt erst, wenn die andere Seite zustimmt.

Neu hier? Siehe INSTALL.md.

Nichts im MCP-Server weiß, ob es die lokale oder die entfernte Seite ist. AGENT_ID und BROKER_URL sind der einzige Unterschied.

Verbinden eines Agenten

Zuerst muss irgendwo ein Vermittler laufen – eine Maschine, ein Befehl, und es kann ein Laptop sein. INSTALL.md behandelt das ausführlich; die Kurzfassung ist npm run broker und npm run tunnel, was eine öffentliche URL ausgibt.

Sobald ein Vermittler existiert, benötigt jede Agentenmaschine drei Dinge: den Code, die Vermittler-URL und das gemeinsame Token.

git clone https://github.com/rockerritesh/tincan.git ~/tincan && cd ~/tincan && npm install

Wenn der Vermittler auf einem von dir verwalteten Server bereitgestellt ist, frage nach seiner aktuellen URL – sie ändert sich jedes Mal, wenn der Tunnel neu startet:

./deploy/url.sh

Registriere den MCP-Server. AGENT_ID ist der name pro Maschine – wähle auf jeder Maschine einen anderen; das Token ist überall gleich.

claude mcp add tincan --env AGENT_ID=laptop --env BROKER_URL=https://<current>.trycloudflare.com --env BROKER_TOKEN=<shared-token> -- node ~/tincan/mcp/server.mjs

Bestätige mit broker_health, dann list_agents – jeder Agent, der einen Aufruf getätigt hat, wird dort angezeigt.

Lokal ausführen stattdessen

Um einen Vermittler auf deiner eigenen Maschine statt auf einer entfernten auszuführen:

npm install && npm test

npm run broker

npm run tunnel

npm run tunnel gibt eine öffentliche URL aus und speichert sie in .tunnel-url. Ein lokaler Vermittler startet ohne Token, es sei denn, du setzt BROKER_TOKEN selbst.

Ausführen des Monitors

Jeder Agent sollte check_inbox in einem Intervall abfragen, um zu bemerken, was der andere sendet. Starte die Sitzung in Claude Code mit:

/loop 30s call check_inbox and handle anything it returns

Ein check_inbox-Aufruf erledigt drei Aufgaben: Er gibt neue Nachrichten zurück, zeigt Übertragungsangebote an, die auf eine Entscheidung warten, und schließt Angebote ab, die dieser Agent gesendet hat und inzwischen beantwortet wurden. Wenn es nichts zu tun gibt, gibt er quiet: true zurück.

Die Werkzeuge

Wie eine Nachricht wandert

Unter 64 KB – send_message sendet sie, der Vermittler hängt sie an das Thread-Log an und legt einen Eintrag im Posteingangsordner des Empfängers ab. Der nächste check_inbox-Aufruf des Empfängers setzt sie auf delivered und gibt sie zurück; ack_message setzt sie auf read. Der Sender beobachtet alle drei Zustände mit message_status.

Über 64 KB – die Größe entscheidet, nicht der Agent. send_message hält die Bytes auf der Festplatte des Senders (~/.agent-tunnel/outbox/<agent>/) und veröffentlicht ein Angebot, das nur Betreff, Größe und Inhaltstyp enthält. Der Empfänger sieht es unter offers_awaiting_response und ruft respond_offer auf. Bei Annahme wird die Nutzlast während des nächsten check_inbox-Ticks des Senders hochgeladen – kein Folgeaufruf, keine Agenten-Buchhaltung. Bei Ablehnung wird die lokale Kopie gelöscht und nichts übermittelt.

Die Zustellung erfolgt mindestens einmal: Eine nicht bestätigte Nachricht erscheint bei jedem Tick erneut, sodass ein Absturz zwischen Abruf und Bestätigung die Nachricht erneut zustellt, anstatt sie zu verlieren.

Diagramme werden aus den SVG-Quellen in docs/images/src/ generiert – bearbeite diese und rendere sie mit rsvg-convert -w 2400 -h 1350 in.svg -o out.png neu.

Der Ordner

Alles, was der Vermittler weiß, befindet sich unter data/, lesbar mit cat und ls:

data/
  messages/<message_id>.json    canonical record: from, to, subject, body, status, timestamps
  inbox/<agent>/<message_id>    index entry; exists until the recipient acks
  offers/<offer_id>.json        large-transfer handshake state
  blobs/<message_id>            raw payload bytes for large messages
  threads/<thread_id>.jsonl     append-only history, one JSON event per line
  agents/<agent_id>.json        first seen / last seen

Threads sind der Gesprächsverlauf und werden niemals abgeschnitten: jedes Senden, Zustellen, Lesen, Angebot, Annehmen und Übertragen ist eine Zeile, der Reihe nach.

tail -f data/threads/*.jsonl

Sicherheitslage

Ein ohne BROKER_TOKEN gestarteter Vermittler ist offen – jeder, der die Tunnel-URL kennt, kann die Nachrichten deiner Agenten lesen und schreiben. Das ist in Ordnung für eine Minute lokaler Tests mit einer URL, die bei jedem Neustart wechselt, aber nicht in Ordnung für etwas, das dauerhaft läuft. Setze das Token:

BROKER_TOKEN=$(openssl rand -hex 32) npm run broker

Jede Route erfordert dann Authorization: Bearer <token>, und jeder Agent benötigt denselben Wert in seiner Umgebung. /v1/health bleibt absichtlich offen, damit der Tunnel einem Rauchtest unterzogen werden kann. deploy/install.sh schreibt immer ein Token, sodass ein bereitgestellter Vermittler standardmäßig geschlossen ist.

Ein gemeinsames Token bedeutet, dass Agenten durch AGENT_ID unterschieden werden, nicht durch Anmeldeinformationen: Jeder Inhaber des Tokens kann einen beliebigen Agentennamen beanspruchen. Das ist ein vernünftiger Kompromiss zwischen Maschinen, die dir gehören, und das Erste, was geändert werden sollte, wenn sich das Token jemals weiter verbreitet – tokens pro Agent sind eine kleine Änderung an derselben Middleware.

Der Vermittler bindet sich an 127.0.0.1 und wird nie direkt exponiert; cloudflared ist der einzige Zugang. Agenten- und Thread-IDs werden mit ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ validiert, bevor sie als Pfadsegmente verwendet werden, sodass eine konstruierte ID nicht aus dem Datenordner entkommen kann.

Bereitstellen des Vermittlers auf einem Server

deploy/install.sh richtet jeden Debian/Ubuntu-Host ein: Es installiert Node 22 und cloudflared, erstellt einen Systembenutzer agenttunnel, schreibt /etc/agent-tunnel.env (Modus 640) und installiert zwei gehärtete systemd-Units, sodass sowohl der Vermittler als auch der Tunnel nach einem Neustart zurückkommen. Der Code landet in /opt/agent-tunnel, der Nachrichtenordner in /var/lib/agent-tunnel.

Der Vermittler bindet sich nur an 127.0.0.1. cloudflared wählt ausgehend zu Cloudflare, daher ist keine eingehende Firewall-Regel erforderlich und der Host legt keinen öffentlichen Port offen – was auch bedeutet, dass dies auf einer VM ohne externe IP funktioniert.

Für eine über IAP erreichte GCP-VM benenne dein Ziel einmal:

cp deploy/target.env.example deploy/target.env

Fülle Projekt, Zone und Instanz aus – diese Datei ist gitignoriert, sodass Hostnamen nicht im Repository landen. Dann bereitstellen oder aktualisieren:

./deploy/push.sh

Es lädt server/ und shared/ hoch, führt das Installationsskript aus und gibt die öffentliche URL aus. Führe es erneut aus, um Änderungen zu übertragen; die Umgebungsdatei und der Nachrichtenordner bleiben unberührt. Auf einem anderen Host stagiere den Code in /tmp/agent-tunnel-stage und führe deploy/install.sh direkt aus.

Das gemeinsame Geheimnis wird bei der ersten Bereitstellung generiert und in ~/.agent-tunnel/broker-token aufbewahrt. Jeder Agent verwendet dasselbe Token; Agenten werden durch AGENT_ID unterschieden, nicht durch Anmeldeinformationen.

Frage die laufende Bereitstellung nach ihrer aktuellen Adresse:

./deploy/url.sh

Die URL ist nicht stabil. Ein schneller Tunnel wählt jedes Mal einen neuen Hostnamen, wenn der cloudflared-Dienst neu startet, einschließlich jedes Host-Neustarts. Wenn das passiert, lies sie erneut aus und aktualisiere BROKER_URL auf jeder Agentenmaschine. Um sie dauerhaft zu machen, benötigst du einen benannten Tunnel, der ein Cloudflare-Konto mit einer Zone erfordert – siehe INSTALL.md.

Tests

npm test

Umfasst den Speicher (Statusübergänge, mindestens einmalige Zustellung, Abweisung von Pfadmanipulationen, Angebotszustandsautomat), die HTTP-Oberfläche (jede Route, Fehlercodes, das Token-Gate), den Zwei-Agenten-Ablauf von Anfang bis Ende und den MCP-Server, der als echter Subprozess über stdio gesteuert wird.

Lizenz

MIT – siehe LICENSE.