@ruvector/edge

Free Self-Learning AI Swarms at the Edge

Build and deploy self-optimizing AI agent swarms that run entirely in web browsers, mobile devices, and edge servers - without paying for cloud infrastructure.

Imagine having dozens of AI agents working together - analyzing data, routing tasks, making decisions, and getting smarter with every interaction - all running directly in your users' browsers. No API costs. No server bills. No data leaving your network. That's what @ruvector/edge makes possible.

This library gives you everything you need to build distributed AI systems: cryptographic identity for each agent, encrypted communication between them, lightning-fast vector search for finding the right agent for each task, consensus protocols so your agents can coordinate without a central server, and self-learning neural networks that continuously optimize agent routing based on real-world outcomes. It's all compiled to a tiny 364KB WebAssembly binary that runs anywhere JavaScript runs.

The key insight: Instead of paying cloud providers to run your AI infrastructure, you use the computing power that's already there - your users' devices. Each browser becomes a node in your swarm. The more users you have, the more powerful your system becomes - and with built-in self-learning capabilities (LoRA fine-tuning, EWC++ continual learning, ReasoningBank experience replay), your swarm gets smarter over time while still costing you nothing.

┌─────────────────────────────────────────────────────────────────────┐
│                         ZERO COST SWARMS                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐   │
│   │ Browser │◄────►│ Browser │◄────►│  Edge   │◄────►│  Mobile │   │
│   │ Agent A │      │ Agent B │      │ Agent C │      │ Agent D │   │
│   └─────────┘      └─────────┘      └─────────┘      └─────────┘   │
│        │                │                │                │        │
│        └────────────────┴────────────────┴────────────────┘        │
│                              P2P Mesh                               │
│                                                                     │
│   Compute: FREE (runs on user devices)                              │
│   Network: FREE (public relays + P2P)                               │
│   Storage: FREE (distributed across nodes)                          │
│   Scale:   UNLIMITED (each user = new node)                         │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

What You Get

| Capability | Technology | Performance | |------------|------------|-------------| | Agent Identity | Ed25519 signatures | 50,000 ops/sec | | Encryption | AES-256-GCM | 1 GB/sec | | Vector Search | HNSW index | 150x faster than brute force | | Task Routing | Semantic LSH | Sub-millisecond | | Trusted Consensus | Raft protocol | For stable cohorts (teams, rooms) | | Open Swarm | Gossip + CRDT | High-churn, Byzantine-tolerant | | Post-Quantum | Hybrid signatures | Future-proof | | Neural Networks | Spiking + STDP | Bio-inspired learning | | Compression | Adaptive 4-32x | Network-aware | | Web Workers | Worker pool | Parallel ops, non-blocking UI |

What It Costs

| Component | Cloud Solution | @ruvector/edge | |-----------|---------------|----------------| | Compute | $200-500/month | $0 (user's CPU) | | Vector DB | $100-300/month | $0 (in-browser HNSW) | | Encryption | $50-100/month | $0 (built-in AES) | | Bandwidth | $0.09/GB | $0 (P2P direct) | | Consensus | $100-200/month | $0 (built-in Raft) | | Total | $450-1100/month | $0/month |

Full Platform Capabilities

RuVector provides a complete edge AI platform. This package (@ruvector/edge) is the lightweight core. For the full toolkit, install @ruvector/edge-full.

┌─────────────────────────────────────────────────────────────────────────────┐
│                        RUVECTOR EDGE PLATFORM                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  @ruvector/edge (364KB)              @ruvector/edge-full (+8MB)             │
│  ─────────────────────               ───────────────────────────            │
│  ✓ Ed25519 Identity                  Everything in edge, PLUS:              │
│  ✓ AES-256-GCM Encryption                                                   │
│  ✓ HNSW Vector Search                ✓ Graph DB (288KB)                     │
│  ✓ Semantic Task Routing               Neo4j-style API, Cypher queries      │
│  ✓ Raft (trusted cohorts)              Relationship modeling, traversals    │
│  ✓ Gossip + CRDT (open swarms)                                              │
│  ✓ Post-Quantum Crypto               ✓ RVLite Vector DB (260KB)             │
│  ✓ Spiking Neural Networks             SQL + SPARQL + Cypher queries        │
│  ✓ Adaptive Compression                IndexedDB persistence                │
│  ✓ Web Worker Pool                                                          │
│                                                                             │
│  Best for:                           ✓ SONA Neural Router (238KB)           │
│  • Lightweight P2P apps                Self-learning with LoRA              │
│  • Secure messaging                    EWC++ continual learning             │
│  • Trusted team swarms                 ReasoningBank experience replay      │
│  • Mobile/embedded                                                          │
│                                                                             │
│                                      ✓ DAG Workflows (132KB)                │
│                                        Task orchestration                   │
│                                        Dependency resolution                │
│                                        Topological execution                │
│                                                                             │
│                                      ✓ ONNX Embeddings (7.1MB)              │
│                                        6 HuggingFace models                 │
│                                        3.8x parallel speedup                │
│                                        MiniLM, BGE, E5, GTE                 │
│                                                                             │
│                                      Best for:                              │
│                                      • Full RAG pipelines                   │
│                                      • Knowledge graphs                     │
│                                      • Self-learning agents                 │
│                                      • Complex workflows                    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Choose Your Package

# Lightweight core (364KB) - P2P, crypto, vectors, consensus
npm install @ruvector/edge

# Full platform (8.4MB) - adds graph DB, SQL, neural routing, ONNX
npm install @ruvector/edge-full

Using Both Together

// Start with edge core
import init, { WasmIdentity, WasmHnswIndex } from '@ruvector/edge';

// Add full capabilities when needed
import { graph, rvlite, sona, dag } from '@ruvector/edge-full';
import onnxInit from '@ruvector/edge-full/onnx';

Consensus Modes: Trusted vs Open

RuVector provides two coordination strategies for different deployment scenarios:

| Mode | Protocol | When to Use | |------|----------|-------------| | Trusted Cohort | Raft | Private teams, enterprise LANs, known membership, low churn | | Open Swarm | Gossip + CRDT | Public networks, anonymous browsers, high churn, adversarial environments |

// Trusted cohort (Raft) - stable team of 3-7 nodes
const raftNode = new WasmRaftNode('node-1', ['node-1', 'node-2', 'node-3']);
raftNode.start_election();  // Leader election for consistent state

// Open swarm (Gossip + CRDT) - dynamic browser mesh
const gossipNode = new WasmGossipNode(identity);
gossipNode.join_swarm(relayUrl);  // Eventually consistent, Byzantine-tolerant

Why two modes? Raft assumes known membership and trusted nodes - perfect for your dev team or enterprise deployment. But a public browser swarm has nodes joining/leaving constantly and can't trust everyone. Gossip protocols with CRDTs handle this gracefully: no leader election, no membership tracking, eventual consistency that converges even with malicious actors.

Web Workers: Keep the UI Responsive

Heavy operations (vector search, encryption, neural network inference) run in Web Workers to avoid blocking the main thread. The package includes a ready-to-use worker pool:

import { WorkerPool } from '@ruvector/edge/worker-pool';

// Create worker pool (auto-detects CPU cores)
const pool = new WorkerPool(
  new URL('@ruvector/edge/worker', import.meta.url),
  new URL('@ruvector/edge/ruvector_edge_bg.wasm', import.meta.url),
  {
    poolSize: navigator.hardwareConcurrency,
    dimensions: 384,
    useHnsw: true
  }
);

await pool.init();

// Operations run in parallel across workers
await pool.insert(embedding, 'doc-1', { title: 'Hello' });
await pool.insertBatch([
  { vector: emb1, id: 'doc-2' },
  { vector: emb2, id: 'doc-3' },
  { vector: emb3, id: 'doc-4' }
]);

// Search distributed across workers
const results = await pool.search(queryEmbedding, 10);

// Batch search (each query on different worker)
const batchResults = await pool.searchBatch([query1, query2, query3], 10);

// Pool statistics
console.log(pool.getStats());
// { poolSize: 8, busyWorkers: 2, idleWorkers: 6, pendingRequests: 0 }

// Clean up
pool.terminate();

Worker Pool Features:

• Round-robin task distribution with load balancing
• Automatic batch splitting across workers
• Promise-based API with 30s timeout
• Zero-copy transfers via transferable objects
• Works in browsers, Deno, and Cloudflare Workers

Quick Start

npm install @ruvector/edge

import init, { WasmIdentity, WasmHnswIndex, WasmSemanticMatcher } from '@ruvector/edge';

await init();

// Create agent identity
const identity = WasmIdentity.generate();
console.log(`Agent: ${identity.agent_id()}`);

// Vector search (150x faster)
const index = new WasmHnswIndex(128, 16, 200);
index.insert("agent-1", new Float32Array(128));

// Semantic task routing
const matcher = new WasmSemanticMatcher();
matcher.register_agent("coder", "rust typescript javascript");
const best = matcher.find_best_agent("write a function");

Table of Contents

1. Why Edge-First?
2. Features
3. Tutorial: Build Your First Swarm
4. P2P Transport Options
5. Free Infrastructure
6. Architecture
7. API Reference
8. Performance
9. Security

Why Edge-First?

| Traditional Cloud Swarms | RuVector Edge Swarms | |--------------------------|---------------------| | Pay per API call | Free forever | | Data leaves your network | Data stays local | | Central point of failure | Fully distributed | | Vendor lock-in | Open source | | High latency (round-trip to cloud) | Sub-millisecond (peer-to-peer) | | Limited by server capacity | Scales with your devices |

The Economics of Edge AI

Cloud AI Swarm (10 agents, 1M operations/month):
├── API calls:        $500-2000/month
├── Compute:          $200-500/month
├── Bandwidth:        $50-100/month
└── Total:            $750-2600/month

RuVector Edge Swarm:
├── Infrastructure:   $0
├── API calls:        $0
├── Bandwidth:        $0 (P2P)
└── Total:            $0/month forever

How Is It Free?

The code runs on devices you already own - there's no server to pay for:

Traditional Architecture:
┌──────────┐     ┌─────────────────┐     ┌──────────┐
│ Agent A  │────►│  Cloud Server   │◄────│ Agent B  │
└──────────┘     │  ($$$$/month)   │     └──────────┘
                 └─────────────────┘

Edge Architecture:
┌──────────┐◄───────────────────────────►┌──────────┐
│ Agent A  │         Direct P2P          │ Agent B  │
│ (Browser)│         Connection          │ (Browser)│
└──────────┘                             └──────────┘
                 No server = No cost

Features

| Feature | Description | |---------|-------------| | Ed25519 Identity | Cryptographic agent identity with signing | | AES-256-GCM | Authenticated encryption for all messages | | Post-Quantum Hybrid | Future-proof against quantum attacks | | HNSW Vector Index | 150x faster similarity search | | Semantic Matching | Intelligent task-to-agent routing | | Raft Consensus | Distributed leader election | | Spiking Networks | Bio-inspired temporal learning | | Adaptive Compression | Network-aware bandwidth optimization |

Quick Start

Installation

npm install @ruvector/edge

Basic Usage

import init, {
  WasmIdentity,
  WasmCrypto,
  WasmHnswIndex,
  WasmSemanticMatcher
} from '@ruvector/edge';

// Initialize WASM (required once)
await init();

// Create an agent
const agent = WasmIdentity.generate();
console.log(`Agent: ${agent.agent_id()}`);

// Encrypt a message
const crypto = new WasmCrypto();
const key = crypto.generate_key();
const encrypted = crypto.encrypt(key, new TextEncoder().encode("Hello swarm!"));

// Search vectors
const index = new WasmHnswIndex(128, 16, 200);
index.insert("doc-1", new Float32Array(128).fill(0.5));
const results = index.search(new Float32Array(128).fill(0.5), 5);

// Route tasks
const matcher = new WasmSemanticMatcher();
matcher.register_agent("coder", "rust typescript javascript");
const best = matcher.find_best_agent("write a function");

Tutorial: Build Your First Swarm

This tutorial walks you through building a complete AI agent swarm that runs entirely in browsers with no backend.

Prerequisites

mkdir my-swarm && cd my-swarm
npm init -y
npm install @ruvector/edge

Create index.html:

<!DOCTYPE html>
<html>
<head><title>My AI Swarm</title></head>
<body>
  <div id="status"></div>
  <script type="module" src="swarm.js"></script>
</body>
</html>

Step 1: Agent Identity

Every agent needs a unique cryptographic identity. This enables signing messages and verifying authenticity.

Create swarm.js:

import init, { WasmIdentity } from '@ruvector/edge';

async function createAgent(name) {
  await init();

  // Generate Ed25519 keypair
  const identity = WasmIdentity.generate();

  console.log(`Agent: ${name}`);
  console.log(`  ID: ${identity.agent_id()}`);
  console.log(`  Public Key: ${identity.public_key_hex().slice(0, 16)}...`);

  return identity;
}

// Create our agent
const myAgent = await createAgent("Worker-001");

// Sign a message to prove identity
const message = new TextEncoder().encode("I am Worker-001");
const signature = myAgent.sign(message);
console.log(`  Signature: ${signature.slice(0, 8).join(',')}...`);

// Verify the signature
const isValid = myAgent.verify(message, signature);
console.log(`  Valid: ${isValid}`); // true

What's happening:

• WasmIdentity.generate() creates an Ed25519 keypair
• agent_id() returns a unique identifier derived from the public key
• sign() creates a cryptographic signature proving the message came from this agent
• verify() checks if a signature is valid

Step 2: Secure Communication

Agents need to encrypt messages so only intended recipients can read them.

import init, { WasmIdentity, WasmCrypto } from '@ruvector/edge';

await init();

const crypto = new WasmCrypto();

// Agent A wants to send a secret message to Agent B
const agentA = WasmIdentity.generate();
const agentB = WasmIdentity.generate();

// Generate a shared secret key (in real app, use key exchange)
const sharedKey = crypto.generate_key();

// Agent A encrypts
const plaintext = new TextEncoder().encode(JSON.stringify({
  task: "analyze_data",
  payload: { dataset: "sales_2024.csv" }
}));

const ciphertext = crypto.encrypt(sharedKey, plaintext);
console.log(`Encrypted: ${ciphertext.length} bytes`);

// Agent B decrypts
const decrypted = crypto.decrypt(sharedKey, ciphertext);
const message = JSON.parse(new TextDecoder().decode(decrypted));
console.log(`Decrypted: ${message.task}`); // "analyze_data"

Security features:

• AES-256-GCM authenticated encryption
• Random nonce per message (replay protection)
• Ciphertext integrity verification

Step 3: Vector Search

Agents need to find each other based on capabilities. HNSW enables fast similarity search.

import init, { WasmHnswIndex } from '@ruvector/edge';

await init();

// Create index: 128 dimensions, M=16 connections, ef=200 search quality
const index = new WasmHnswIndex(128, 16, 200);

// Register agents with their capability embeddings
// (In production, use real embeddings from a model)
function mockEmbedding(weights) {
  const vec = new Float32Array(128);
  weights.forEach((w, i) => vec[i] = w);
  return vec;
}

// Register specialized agents
index.insert("rust-expert", mockEmbedding([0.9, 0.1, 0.0, 0.0]));
index.insert("python-expert", mockEmbedding([0.1, 0.9, 0.0, 0.0]));
index.insert("ml-expert", mockEmbedding([0.0, 0.5, 0.9, 0.0]));
index.insert("devops-expert", mockEmbedding([0.0, 0.0, 0.2, 0.9]));

console.log(`Index size: ${index.len()} agents`);

// Find best agent for a Rust task
const rustTask = mockEmbedding([0.85, 0.1, 0.05, 0.0]);
const results = index.search(rustTask, 3);

console.log("Best agents for Rust task:");
results.forEach(([id, distance]) => {
  console.log(`  ${id}: distance=${distance.toFixed(3)}`);
});
// Output: rust-expert: distance=0.050

Why HNSW?

• O(log n) search instead of O(n)
• 150x faster than brute force at 10K+ vectors
• Memory-efficient graph structure

Step 4: Task Routing

Route tasks to the best agent using semantic matching.

import init, { WasmSemanticMatcher } from '@ruvector/edge';

await init();

const matcher = new WasmSemanticMatcher();

// Register agents with capability descriptions
matcher.register_agent("code-agent",
  "rust typescript javascript python programming coding functions classes");
matcher.register_agent("data-agent",
  "python pandas numpy data analysis statistics csv excel");
matcher.register_agent("devops-agent",
  "docker kubernetes terraform aws deploy infrastructure cicd");
matcher.register_agent("writing-agent",
  "documentation markdown readme technical writing blog");

console.log(`Registered ${matcher.agent_count()} agents`);

// Route tasks to best agent
const tasks = [
  "Write a Rust function to parse JSON",
  "Analyze the sales data in this CSV",
  "Deploy the app to Kubernetes",
  "Update the API documentation"
];

tasks.forEach(task => {
  const best = matcher.find_best_agent(task);
  console.log(`"${task.slice(0, 30)}..." → ${best}`);
});

// Output:
// "Write a Rust function..." → code-agent
// "Analyze the sales data..." → data-agent
// "Deploy the app to Kube..." → devops-agent
// "Update the API documen..." → writing-agent

How it works:

• LSH (Locality-Sensitive Hashing) creates semantic fingerprints
• Tasks are matched to agents by fingerprint similarity
• Sub-millisecond routing even with many agents

Step 5: Distributed Consensus

When multiple agents need to agree on a leader or shared state, use Raft consensus.

import init, { WasmRaftNode } from '@ruvector/edge';

await init();

// Create a 3-node cluster
const members = ["node-1", "node-2", "node-3"];

const node1 = new WasmRaftNode("node-1", members);
const node2 = new WasmRaftNode("node-2", members);
const node3 = new WasmRaftNode("node-3", members);

console.log(`Node 1 state: ${node1.state()}`); // "follower"
console.log(`Node 1 term: ${node1.current_term()}`); // 0

// Node 1 times out and starts election
const voteRequest = node1.start_election();
console.log(`Node 1 state: ${node1.state()}`); // "candidate"
console.log(`Node 1 term: ${node1.current_term()}`); // 1

// Simulate: Node 2 and 3 grant votes
// (In real app, send voteRequest over network, receive responses)
const granted1 = node1.receive_vote(true);
const granted2 = node1.receive_vote(true);

console.log(`Node 1 state: ${node1.state()}`); // "leader"

// Leader can now coordinate the swarm!
console.log("Leader elected - swarm can coordinate");

Raft guarantees:

• Only one leader at a time
• Leader election in 1-2 round trips
• Tolerates f failures in 2f+1 nodes

P2P Transport Options

RuVector Edge provides the intelligence layer. You need a transport layer for agents to communicate. Here are your free options:

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    @ruvector/edge (WASM)                    │
│  Identity, Crypto, HNSW, Semantic Matching, Raft, etc.      │
└─────────────────────────────────────────────────────────────┘
                              │
                    Transport Layer (choose one)
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
   ┌─────────┐          ┌─────────┐          ┌─────────┐
   │ WebRTC  │          │  GUN.js │          │  IPFS/  │
   │  (P2P)  │          │  (P2P)  │          │ libp2p  │
   └─────────┘          └─────────┘          └─────────┘

Option 1: WebRTC (Browser-to-Browser)

Best for: Direct browser-to-browser communication Cost: Free (need minimal signaling server)

import init, { WasmIdentity, WasmCrypto } from '@ruvector/edge';

await init();

const identity = WasmIdentity.generate();
const crypto = new WasmCrypto();

// Create peer connection
const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] // Free STUN
});

// Create data channel for agent messages
const channel = pc.createDataChannel('swarm');

channel.onopen = () => {
  console.log('P2P connection established!');

  // Send encrypted message
  const key = crypto.generate_key(); // Exchange via signaling
  const message = { type: 'task', data: 'analyze this' };
  const encrypted = crypto.encrypt(key,
    new TextEncoder().encode(JSON.stringify(message))
  );

  channel.send(encrypted);
};

channel.onmessage = (event) => {
  const decrypted = crypto.decrypt(key, new Uint8Array(event.data));
  const message = JSON.parse(new TextDecoder().decode(decrypted));
  console.log('Received:', message);
};

// Signaling (exchange offer/answer via any method)
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
// Send offer to peer via signaling server, WebSocket, or even QR code

Free signaling options:

• PeerJS Cloud (free tier)
• Firebase Realtime Database (free tier)
• Your own WebSocket on Fly.io/Railway free tier

Option 2: GUN.js (Decentralized Database)

Best for: Real-time sync, offline-first, no server needed Cost: Completely free (public relay network)

import init, { WasmIdentity, WasmSemanticMatcher } from '@ruvector/edge';
import Gun from 'gun';

await init();

const identity = WasmIdentity.generate();
const matcher = new WasmSemanticMatcher();

// Connect to public GUN relays (free!)
const gun = Gun(['https://gun-manhattan.herokuapp.com/gun']);

// Create swarm namespace
const swarm = gun.get('my-ai-swarm');

// Register this agent
swarm.get('agents').get(identity.agent_id()).put({
  id: identity.agent_id(),
  capabilities: 'rust typescript programming',
  publicKey: identity.public_key_hex(),
  online: true,
  timestamp: Date.now()
});

// Listen for new agents
swarm.get('agents').map().on((agent, id) => {
  if (agent && agent.id !== identity.agent_id()) {
    console.log(`Discovered agent: ${agent.id}`);
    matcher.register_agent(agent.id, agent.capabilities);
  }
});

// Publish tasks
swarm.get('tasks').set({
  id: crypto.randomUUID(),
  description: 'Write a Rust function',
  from: identity.agent_id(),
  timestamp: Date.now()
});

// Listen for tasks
swarm.get('tasks').map().on((task) => {
  if (task) {
    const bestAgent = matcher.find_best_agent(task.description);
    if (bestAgent === identity.agent_id()) {
      console.log(`I should handle: ${task.description}`);
    }
  }
});

Why GUN?

• No server required - uses public relays
• Offline-first with automatic sync
• Real-time updates via WebSocket
• Already integrated in RuVector Edge (Rust side)

Option 3: IPFS + libp2p

Best for: Content-addressed storage + P2P messaging Cost: Free (self-host) or free tier (Pinata, Infura)

import init, { WasmIdentity, WasmCrypto } from '@ruvector/edge';
import { createLibp2p } from 'libp2p';
import { webSockets } from '@libp2p/websockets';
import { noise } from '@chainsafe/libp2p-noise';
import { gossipsub } from '@chainsafe/libp2p-gossipsub';

await init();

const identity = WasmIdentity.generate();
const crypto = new WasmCrypto();

// Create libp2p node
const node = await createLibp2p({
  transports: [webSockets()],
  connectionEncryption: [noise()],
  pubsub: gossipsub()
});

await node.start();

// Subscribe to swarm topic
const topic = 'my-ai-swarm';

node.pubsub.subscribe(topic);
node.pubsub.addEventListener('message', (event) => {
  if (event.detail.topic === topic) {
    const message = JSON.parse(new TextDecoder().decode(event.detail.data));
    console.log('Received:', message);
  }
});

// Publish to swarm
node.pubsub.publish(topic, new TextEncoder().encode(JSON.stringify({
  from: identity.agent_id(),
  type: 'announce',
  capabilities: ['rust', 'wasm']
})));

IPFS for artifacts:

import { create } from 'ipfs-http-client';

// Use free Infura IPFS gateway
const ipfs = create({ url: 'https://ipfs.infura.io:5001' });

// Store agent output
const result = await ipfs.add(JSON.stringify({
  task: 'analyze-data',
  output: { summary: '...' },
  agent: identity.agent_id(),
  signature: identity.sign(...)
}));

console.log(`Stored at: ipfs://${result.cid}`);

// Share CID with swarm - anyone can fetch

Option 4: Nostr Relays

Best for: Simple pub/sub with free public infrastructure Cost: Free (many public relays)

import init, { WasmIdentity } from '@ruvector/edge';
import { relayInit, getEventHash, signEvent } from 'nostr-tools';

await init();

const identity = WasmIdentity.generate();

// Connect to free public relay
const relay = relayInit('wss://relay.damus.io');
await relay.connect();

// Create Nostr event (signed message)
const event = {
  kind: 29000, // Custom kind for AI swarm
  created_at: Math.floor(Date.now() / 1000),
  tags: [['swarm', 'my-ai-swarm']],
  content: JSON.stringify({
    agentId: identity.agent_id(),
    type: 'task',
    data: 'Write a function'
  })
};

// Sign with identity (Nostr uses secp256k1, so bridge needed)
// Or use Nostr's native keys alongside RuVector identity

// Subscribe to swarm events
const sub = relay.sub([
  { kinds: [29000], '#swarm': ['my-ai-swarm'] }
]);

sub.on('event', (event) => {
  const message = JSON.parse(event.content);
  console.log(`From ${message.agentId}: ${message.type}`);
});

Transport Comparison

| Transport | Latency | Offline | Complexity | Best For | |-----------|---------|---------|------------|----------| | WebRTC | ~50ms | No | Medium | Real-time, gaming | | GUN.js | ~100ms | Yes | Low | General purpose | | IPFS/libp2p | ~200ms | Partial | High | Content storage | | Nostr | ~150ms | No | Low | Simple messaging |

Recommended: Start with GUN.js

npm install gun @ruvector/edge

GUN requires zero setup, works offline, and has a free public relay network.

Free Infrastructure (Zero Cost at Any Scale)

The entire stack can run for $0/month using public infrastructure:

Free GUN Relays (Unlimited)

const gun = Gun([
  'https://gun-manhattan.herokuapp.com/gun',
  'https://gun-us.herokuapp.com/gun',
  'https://gunjs.herokuapp.com/gun',
  'https://gun-eu.herokuapp.com/gun'
]);
// No signup, no limits, community-run

Free STUN Servers (WebRTC)

const rtcConfig = {
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },      // Google
    { urls: 'stun:stun1.l.google.com:19302' },     // Google
    { urls: 'stun:stun.cloudflare.com:3478' },     // Cloudflare
    { urls: 'stun:stun.services.mozilla.com' },    // Mozilla
    { urls: 'stun:stun.stunprotocol.org:3478' }    // Open source
  ]
};
// Unlimited, no account needed

Free TURN Servers (NAT Traversal)

| Provider | Free Tier | Signup | |----------|-----------|--------| | Metered.ca | 500MB/month | Yes | | Xirsys | 500MB/month | Yes | | Twilio | $15 free credit | Yes | | OpenRelay | Unlimited | No |

Free Signaling Services

| Service | Free Tier | Best For | |---------|-----------|----------| | PeerJS Cloud | Unlimited connections | WebRTC signaling | | Firebase Realtime | 1GB storage, 10GB/month | Real-time sync | | Supabase Realtime | 500MB, unlimited connections | PostgreSQL + realtime | | Ably | 6M messages/month | Pub/sub | | Pusher | 200K messages/day | Simple messaging |

Free Nostr Relays (Unlimited)

const NOSTR_RELAYS = [
  'wss://relay.damus.io',
  'wss://nos.lol',
  'wss://relay.nostr.band',
  'wss://nostr.wine',
  'wss://relay.snort.social'
];
// No signup, no limits, decentralized

Free Self-Hosting

| Platform | Free Tier | Use Case | |----------|-----------|----------| | Fly.io | 3 shared VMs, 160GB transfer | GUN/WebSocket relay | | Railway | $5 credit/month | Any relay | | Render | 750 hours/month | Static + WebSocket | | Cloudflare Workers | 100K requests/day | Edge signaling | | Deno Deploy | 1M requests/month | Edge relay | | Vercel Edge | 1M invocations/month | Signaling |

Complete Free Stack Example

import init, { WasmIdentity, WasmSemanticMatcher } from '@ruvector/edge';
import Gun from 'gun';

await init();

// 1. Free GUN relays (unlimited scale)
const gun = Gun(['https://gun-manhattan.herokuapp.com/gun']);

// 2. Free WebRTC STUN (unlimited)
const rtcConfig = {
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },
    { urls: 'stun:stun.cloudflare.com:3478' }
  ]
};

// 3. Your swarm - $0/month forever
const identity = WasmIdentity.generate();
const matcher = new WasmSemanticMatcher();
const swarm = gun.get('my-ai-swarm');

// Register agent
swarm.get('agents').get(identity.agent_id()).put({
  id: identity.agent_id(),
  capabilities: 'coding analysis research',
  publicKey: identity.public_key_hex(),
  online: true
});

// Discover other agents
swarm.get('agents').map().on((agent, id) => {
  if (agent && agent.id !== identity.agent_id()) {
    matcher.register_agent(agent.id, agent.capabilities);
    console.log(`Discovered: ${agent.id}`);
  }
});

// Route and execute tasks
swarm.get('tasks').map().on((task) => {
  if (task) {
    const best = matcher.find_best_agent(task.description);
    if (best === identity.agent_id()) {
      console.log(`Handling: ${task.description}`);
      // Execute task...
    }
  }
});

Cost Summary

| Scale | Infrastructure | Monthly Cost | |-------|----------------|--------------| | 1 - 10K users | Public GUN + Google STUN | $0 | | 10K - 100K users | Public GUN + Google STUN | $0 | | 100K - 1M users | Public GUN + Google STUN | $0 | | 1M+ users | Public GUN + Google STUN | $0 | | Any scale (private) | Fly.io free tier | $0 | | Enterprise (dedicated) | Self-hosted VPS | $5-20 |

Key insight: Public infrastructure scales infinitely. You only pay if you want private/dedicated relays.

Architecture

Complete System

┌─────────────────────────────────────────────────────────────────────────┐
│                              Your Application                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │                      @ruvector/edge (WASM)                       │   │
│   │                                                                  │   │
│   │   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │   │
│   │   │ Identity │  │  Crypto  │  │   HNSW   │  │ Semantic │        │   │
│   │   │ Ed25519  │  │ AES-GCM  │  │  Index   │  │ Matcher  │        │   │
│   │   └──────────┘  └──────────┘  └──────────┘  └──────────┘        │   │
│   │                                                                  │   │
│   │   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │   │
│   │   │   Raft   │  │ Hybrid   │  │ Spiking  │  │Quantizer │        │   │
│   │   │Consensus │  │Post-QC   │  │ Neural   │  │Compress  │        │   │
│   │   └──────────┘  └──────────┘  └──────────┘  └──────────┘        │   │
│   │                                                                  │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                                    │                                     │
│                          Transport Adapter                               │
│                                    │                                     │
│   ┌────────────────┬───────────────┼───────────────┬────────────────┐   │
│   │                │               │               │                │   │
│   ▼                ▼               ▼               ▼                ▼   │
│ WebRTC          GUN.js          libp2p          Nostr           Custom  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
         │                │                │                │
         ▼                ▼                ▼                ▼
    ┌─────────┐      ┌─────────┐      ┌─────────┐      ┌─────────┐
    │ Browser │      │ Browser │      │  Edge   │      │  Node   │
    │ Agent A │◄────►│ Agent B │◄────►│ Agent C │◄────►│ Agent D │
    └─────────┘      └─────────┘      └─────────┘      └─────────┘
                           │
                   No Central Server
                   No Cloud Costs
                   No Data Leakage

What Runs Where

| Component | Runs On | Cost | |-----------|---------|------| | RuVector Edge (WASM) | User's browser/device | Free - their CPU | | Vector index (HNSW) | User's browser/device | Free - their RAM | | Encryption (AES-GCM) | User's browser/device | Free - their CPU | | Raft consensus | Distributed across agents | Free - P2P | | Transport (GUN/WebRTC) | P2P or free relays | Free |

API Reference

WasmIdentity

const id = WasmIdentity.generate();
id.agent_id()           // Unique identifier
id.public_key_hex()     // Hex public key
id.sign(Uint8Array)     // Sign message
id.verify(msg, sig)     // Verify signature

WasmCrypto

const crypto = new WasmCrypto();
crypto.generate_key()            // 32-byte key
crypto.encrypt(key, plaintext)   // AES-256-GCM
crypto.decrypt(key, ciphertext)  // Decrypt

WasmHnswIndex

const index = new WasmHnswIndex(dims, m, ef);
index.insert(id, Float32Array)   // Add vector
index.search(query, k)           // Find k nearest
index.len()                      // Count

WasmSemanticMatcher

const matcher = new WasmSemanticMatcher();
matcher.register_agent(id, capabilities)
matcher.find_best_agent(task)
matcher.agent_count()

WasmRaftNode

const raft = new WasmRaftNode(id, members);
raft.start_election()    // Become candidate
raft.receive_vote(bool)  // Handle vote
raft.state()             // "follower"|"candidate"|"leader"
raft.current_term()      // Raft term number

WasmHybridKeyPair

const keys = WasmHybridKeyPair.generate();
keys.sign(message)       // Post-quantum signature
keys.verify(signature)   // Verify
keys.public_key_bytes()  // Export

WasmSpikingNetwork

const net = new WasmSpikingNetwork(in, hidden, out);
net.forward(spikes)              // Process
net.stdp_update(pre, post, lr)   // Learn
net.reset()                      // Reset state

WasmQuantizer

const q = new WasmQuantizer();
q.quantize(Float32Array)    // 4x compression
q.reconstruct(Uint8Array)   // Restore

WasmAdaptiveCompressor

const comp = new WasmAdaptiveCompressor();
comp.update_metrics(bandwidth, latency)
comp.compress(data)
comp.decompress(data)
comp.condition()  // "excellent"|"good"|"poor"|"critical"

Performance

| Operation | Speed | Notes | |-----------|-------|-------| | Identity generation | 0.5ms | Ed25519 keypair | | Sign message | 0.02ms | 50,000 ops/sec | | AES-256-GCM encrypt | 1GB/sec | Hardware accelerated | | HNSW search (10K vectors) | 0.1ms | 150x faster than brute | | Semantic match | 0.5ms | LSH-based | | Raft election | 1ms | Single round-trip | | Quantization | 100M floats/sec | 4x compression | | WASM load | ~50ms | 364KB binary |

Security

• Ed25519 - Elliptic curve signatures (128-bit security)
• X25519 - Secure key exchange
• AES-256-GCM - Authenticated encryption
• Post-Quantum Hybrid - Ed25519 + Dilithium-style
• Zero-Trust - Verify all messages
• Replay Protection - Nonces and timestamps

Interactive Swarm Generator

Don't know where to start? We've included an interactive code generator that helps you build swarm configurations visually. Just select your options and get production-ready code instantly.

How to Use the Generator

# Option 1: Use a local server (recommended)
npm install @ruvector/edge
npx serve node_modules/@ruvector/edge/
# Then open http://localhost:3000/generator.html

# Option 2: Open directly in browser
# Navigate to: node_modules/@ruvector/edge/generator.html

The generator runs live demos directly in your browser using the actual WASM library - you can test everything before copying the code.

What You Can Configure

Network Topologies - How agents connect to each other:

| Topology | Best For | Description | |----------|----------|-------------| | Mesh | General purpose | Every agent can talk to every other agent directly | | Star | Centralized control | All agents connect through one coordinator | | Hierarchical | Large organizations | Tree structure with managers and workers | | Ring | Sequential processing | Messages pass around in a circle | | Gossip | Eventual consistency | Information spreads like rumors | | Sharded | Domain separation | Different groups handle different topics |

Transport Layers - How messages travel between agents:

| Transport | Latency | Offline? | Best For | |-----------|---------|----------|----------| | GUN.js | ~100ms | Yes | Getting started, offline-first apps | | WebRTC | ~50ms | No | Real-time gaming, video, low latency | | libp2p | ~200ms | Partial | IPFS integration, content addressing | | Nostr | ~150ms | No | Decentralized social, simple pub/sub |

Use Cases - Pre-built patterns for common scenarios:

| Use Case | What It Does | |----------|--------------| | AI Assistants | Multiple specialized agents handling different types of questions | | Data Pipeline | Distributed ETL with parallel processing stages | | Multiplayer Gaming | Real-time game state sync with authoritative host | | IoT Swarm | Coordinate sensors and actuators across locations | | Marketplace | Agents that negotiate, bid, and trade autonomously | | Research Compute | Distribute calculations across many devices |

Features - Building blocks you can mix and match:

| Feature | What It Adds | |---------|--------------| | Identity | Ed25519 cryptographic keypairs for each agent | | Encryption | AES-256-GCM for all messages | | HNSW Index | Fast similarity search (150x faster than brute force) | | Semantic Matching | Route tasks to the best agent automatically | | Raft Consensus | Elect leaders and agree on shared state | | Post-Quantum | Future-proof signatures against quantum computers | | Spiking Neural | Bio-inspired learning and pattern recognition | | Compression | Adaptive bandwidth optimization (4-32x) |

Exotic Patterns - Advanced capabilities for specialized needs:

| Pattern | What It Does | |---------|--------------| | MCP Tools | Browser-based Model Context Protocol for AI collaboration | | Byzantine Fault | Tolerate malicious or faulty nodes | | Quantum Resistant | Hybrid signatures safe from future quantum attacks | | Neural Consensus | Use spiking networks for group decisions | | Swarm Intelligence | Particle swarm optimization for problem solving | | Self-Healing | Automatic failure detection and recovery | | Emergent Behavior | Evolutionary algorithms for agent adaptation |

Browser-Based MCP Tools

The generator includes a complete MCP (Model Context Protocol) implementation that runs entirely in the browser. This lets you create AI tools that work with Claude and other MCP-compatible systems, but without needing a server.

// Create a browser-based MCP server
const mcp = new BrowserMCPServer();
await mcp.init();

// Built-in tools ready to use:
// - discover_agents: Find the right agent for a task
// - send_secure_message: Encrypted P2P communication
// - store_memory: Save vectors for semantic search
// - search_memory: Find similar items by meaning
// - sign_message: Cryptographically prove authorship

// Example: Route a request to find coding help
const response = await mcp.handleRequest({
  method: 'tools/call',
  params: {
    name: 'discover_agents',
    arguments: { query: 'help me write a Python script' }
  }
});

// Connect multiple MCP servers for collaboration
const network = new MCPCollaborativeNetwork();
await network.addServer('coder', 'programming development');
await network.addServer('analyst', 'data analysis statistics');
await network.addServer('writer', 'documentation technical writing');

// Requests automatically route to the best server
const result = await network.routeRequest(request);

Why browser-based MCP?

• No server costs - runs on user devices
• Works offline - all tools available without internet
• Privacy-first - sensitive data never leaves the browser
• Instant deployment - just include the library

License

MIT License - Free for commercial and personal use.

Next Steps

1. Install: npm install @ruvector/edge
2. Try the tutorial: Build your first swarm
3. Choose transport: Start with GUN.js
4. Scale: Add more agents as needed

Stop paying for cloud AI. Start running free edge swarms.

GitHub | npm | Issues