Clawdio

Clawdio

Minimal secure peer-to-peer communication for AI agents. Two agents exchange a connection string, perform a Noise XX handshake, then communicate over encrypted channels. No central server required.

When to Use

Setup

The Clawdio project lives at projects/clawdio/. Install dependencies and build:

cd projects/clawdio && npm install && npx tsc

Quick Start

const { Clawdio } = require('./projects/clawdio/dist/index.js');
// Create two nodes
const alice = await Clawdio.create({ port: 9090, autoAccept: true });
const bob = await Clawdio.create({ port: 9091, autoAccept: true });
// Connect (Noise XX handshake)
const aliceId = await bob.exchangeKeys(alice.getConnectionString());
// Send messages
await bob.send(aliceId, { task: "What's the weather?" });
alice.onMessage((msg, from) => console.log(msg.task));

Connection Consent (Recommended)

By default, unknown inbound peers require explicit consent:

const node = await Clawdio.create({ port: 9090 }); // autoAccept defaults to false
node.on('connectionRequest', (req) => {
  console.log(Connection from ${req.id});
  console.log(Fingerprint: ${req.fingerprint});
  // Accept or reject
  node.acceptPeer(req.id);  // or node.rejectPeer(req.id)
});

Outbound connections (you calling exchangeKeys) are auto-accepted. Already-trusted peers auto-reconnect.

Human Verification

For high-trust scenarios, verify peers in person:

node.setOwner('Alice');
const code = node.getVerificationCode(peerId); // "torch lemon onyx prism jade index"
// Both humans compare codes in person, then:
node.verifyPeer(peerId); // trust: 'accepted' → 'human-verified'
node.getPeerTrust(peerId); // 'human-verified'

Trust Levels

Persistent Identity

Pass identityPath to persist keys and trusted peers across restarts:

const node = await Clawdio.create({
  port: 9090,
  identityPath: '.clawdio-identity.json'
});

Sub-Agent Pattern

Spawn a sub-agent to handle Clawdio communication:

1. Main agent spawns sub-agent with task
2. Sub-agent creates Clawdio node, connects to remote peer
3. Sub-agent exchanges messages, collects results
4. Sub-agent reports back to main agent

Security Properties

API Reference

| Method | Description | |--------|-------------| | Clawdio.create(opts) | Create and start a node | | node.exchangeKeys(connStr) | Connect to peer | | node.send(peerId, msg) | Send encrypted message | | node.onMessage(handler) | Listen for messages | | node.acceptPeer(id) | Accept pending connection | | node.rejectPeer(id) | Reject pending connection | | node.setOwner(name) | Set human owner name | | node.getVerificationCode(id) | Get 6-word verification code | | node.verifyPeer(id) | Mark peer as human-verified | | node.getPeerTrust(id) | Get trust level | | node.getFingerprint(id) | Emoji fingerprint | | node.getPeerStatus(id) | alive/stale/down | | node.stop() | Shutdown |

const { Clawdio } = require('./projects/clawdio/dist/index.js');
// Create two nodes
const alice = await Clawdio.create({ port: 9090, autoAccept: true });
const bob = await Clawdio.create({ port: 9091, autoAccept: true });
// Connect (Noise XX handshake)
const aliceId = await bob.exchangeKeys(alice.getConnectionString());
// Send messages
await bob.send(aliceId, { task: "What's the weather?" });
alice.onMessage((msg, from) => console.log(msg.task));

The Clawdio project lives at projects/clawdio/. Install dependencies and build:

cd projects/clawdio && npm install && npx tsc