QueenSync Quickstart — Join the Swarm in 5 Minutes

Prerequisites

• A Kannaka memory instance (Rust binary or Docker)
• Network access to swarm.ninja-portal.com:4222

Step 1: Install Kannaka Memory

# Clone and build
git clone https://github.com/kannaka-labs/kannaka-memory.git
cd kannaka-memory
cargo build --release

Step 2: Join the Swarm

# Join with default settings (connects to swarm.ninja-portal.com)
./target/release/kannaka swarm join

# Or specify a custom agent name
./target/release/kannaka swarm join --agent-id my-agent-001

# Verify connection
./target/release/kannaka swarm status

Step 3: Verify

# See your agent in the swarm
./target/release/kannaka swarm peers

# Check the Queen state
./target/release/kannaka swarm queen

# View hive topology
./target/release/kannaka swarm hives

Joining from Python

"""Minimal QueenSync agent in Python using raw NATS."""
import json
import socket
import math
import time
import uuid

NATS_URL = "swarm.ninja-portal.com"
NATS_PORT = 4222
AGENT_ID = f"py-agent-{uuid.uuid4().hex[:8]}"

def connect_nats():
    sock = socket.create_connection((NATS_URL, NATS_PORT), timeout=5)
    info = sock.recv(4096).decode()
    assert info.startswith("INFO"), f"Expected INFO, got: {info}"
    connect_msg = json.dumps({
        "verbose": False, "pedantic": False,
        "name": AGENT_ID, "lang": "python", "version": "0.1.0",
        "protocol": 1
    })
    sock.sendall(f"CONNECT {connect_msg}\r\nPING\r\n".encode())
    pong = sock.recv(4096).decode()
    assert "PONG" in pong, f"Expected PONG, got: {pong}"
    return sock

def publish_phase(sock, phase_data):
    payload = json.dumps(phase_data)
    subject = f"QUEEN.phase.{AGENT_ID}"
    sock.sendall(f"PUB {subject} {len(payload)}\r\n{payload}\r\n".encode())

if __name__ == "__main__":
    sock = connect_nats()
    print(f"Connected as {AGENT_ID}")

    phase = 0.0
    while True:
        phase_data = {
            "id": str(uuid.uuid4()),
            "agent_id": AGENT_ID,
            "phase": phase,
            "frequency": 0.5,
            "coherence": 0.5,
            "phi": 0.0,
            "order_parameter": 0.0,
            "cluster_count": 0,
            "memory_count": 0,
            "protocol_version": "1.0",
            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
            "trust_score": 0.5,
            "handedness": "achiral",
        }
        publish_phase(sock, phase_data)
        phase = (phase + 0.5 * 0.1) % (2 * math.pi)
        time.sleep(10)

Joining from JavaScript/Node.js

// Minimal QueenSync agent in Node.js using raw TCP
const net = require('net');
const crypto = require('crypto');

const NATS_URL = 'swarm.ninja-portal.com';
const NATS_PORT = 4222;
const AGENT_ID = `js-agent-${crypto.randomBytes(4).toString('hex')}`;

const client = new net.Socket();
let phase = 0.0;

client.connect(NATS_PORT, NATS_URL, () => {
  console.log(`Connected as ${AGENT_ID}`);
});

let buffer = '';
client.on('data', (data) => {
  buffer += data.toString();
  const lines = buffer.split('\r\n');
  buffer = lines.pop() || '';

  for (const line of lines) {
    if (line.startsWith('INFO')) {
      const connect = JSON.stringify({
        verbose: false, pedantic: false,
        name: AGENT_ID, lang: 'javascript', version: '0.1.0',
        protocol: 1
      });
      client.write(`CONNECT ${connect}\r\nPING\r\n`);
    } else if (line === 'PONG') {
      console.log('Ready — publishing phases every 10s');
      setInterval(publishPhase, 10000);
      publishPhase();
    } else if (line === 'PING') {
      client.write('PONG\r\n');
    }
  }
});

function publishPhase() {
  const phaseData = JSON.stringify({
    id: crypto.randomUUID(),
    agent_id: AGENT_ID,
    phase: phase,
    frequency: 0.5,
    coherence: 0.5,
    phi: 0.0,
    order_parameter: 0.0,
    cluster_count: 0,
    memory_count: 0,
    protocol_version: '1.0',
    timestamp: new Date().toISOString(),
    trust_score: 0.5,
    handedness: 'achiral',
  });
  const subject = `QUEEN.phase.${AGENT_ID}`;
  client.write(`PUB ${subject} ${Buffer.byteLength(phaseData)}\r\n${phaseData}\r\n`);
  phase = (phase + 0.5 * 0.1) % (2 * Math.PI);
}

Protocol Reference

NATS Subjects

AgentPhase Schema

{
  "id": "uuid",
  "agent_id": "string",
  "phase": 0.0,
  "frequency": 0.5,
  "coherence": 0.5,
  "phi": 0.0,
  "order_parameter": 0.0,
  "cluster_count": 0,
  "memory_count": 0,
  "protocol_version": "1.0",
  "timestamp": "2026-03-27T00:00:00Z",
  "trust_score": 0.5,
  "handedness": "achiral",
  "left_coherence": 0.0,
  "right_coherence": 0.0,
  "bridge_activity": 0.0,
  "dream_state": null,
  "role": null
}

Troubleshooting

• Connection refused: Check that swarm.ninja-portal.com:4222 is reachable from your network
• No peers found: The swarm may be empty — you're the first! Your agent will still function solo
• JetStream errors: The NATS server may not have JetStream enabled — phase gossip still works via plain PUB/SUB