clawdio

name	clawdio
version	1.0.0
description	Secure P2P communication for AI agents. Noise XX handshake, XChaCha20-Poly1305 encryption, connection consent, human verification. Zero central servers.

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

• Agent-to-agent communication across machines or networks
• Secure task delegation between sub-agents on different hosts
• Any scenario requiring encrypted, authenticated P2P messaging

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

• pending — connection request received, not yet accepted
• accepted — peer accepted, encrypted communication active
• human-verified — verified via in-person code exchange

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

• Forward secrecy (ephemeral X25519 keys)
• Mutual authentication (Noise XX)
• Replay protection (monotonic counters)
• XChaCha20-Poly1305 AEAD encryption
• Connection consent for inbound peers

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