Antigravity Swarms
Architecture Pattern 4 Gold-Standard Production Swarm

Method 4: Sovereign WireGuard Mesh & NATS JetStream

Combining a zero-trust private network mesh (Tailscale) with an ultra-lightweight distributed event broker (NATS JetStream) for fault-tolerant multi-agent swarms.

1. The Hybrid Sovereign Blueprint

For enterprise or high-volume developer swarms spanning laptops, headless on-premise servers (like dell5040), and cloud GPUs, point-to-point HTTP calls can suffer cascading timeouts. This pattern decouples networking via Tailscale and task state via NATS JetStream durable consumer groups.

flowchart TB subgraph Tailnet ["Zero-Trust Tailnet Mesh (Encrypted WireGuard 100.x.y.z)"] subgraph NodeA ["Primary Dev Laptop (MacBook Pro)"] A1["Antigravity Orchestrator"] end subgraph NodeB ["Headless Server (dell5040)"] D1["agy-daemon.service (Worker)"] W1["NATS Worker Consumer Daemon"] end subgraph NodeC ["Cloud GPU Box (Ubuntu VPS)"] D2["agy-daemon.service (Worker)"] W2["NATS Worker Consumer Daemon"] end subgraph BrokerNode ["Messaging Hub"] NATS["NATS JetStream Server (:4222)
Subject: tasks.dispatch.*
Durable Consumer Group: 'antigravity_workers'"] KV["NATS Key-Value Store (Blackboard Memory)"] end end A1 == WireGuard UDP ==> NATS W1 == WireGuard UDP ==> NATS W2 == WireGuard UDP ==> NATS A1 -- "1. Publish Task: 'audit-nginx'" --> NATS NATS -- "2. Load-Balanced Push (Ack Required)" --> W1 W1 -- "3. Local Execution via `agentapi`" --> D1 D1 -- "4. Result Artifacts" --> W1 W1 -- "5. Publish Completion & Ack" --> NATS NATS -- "6. Notification Stream" --> A1

2. Technical Pillars: Tailscale Aperture & NATS JetStream

Pillar 1: Tailscale & Aperture AI Gateway

  • Automatic NAT Traversal: STUN UDP hole-punching creates direct P2P connections ~90% of the time. Encrypted DERP relays over port 443 handle symmetric NATs.
  • Tailscale Aperture: Reverse-proxy gateway allowing Antigravity nodes to access remote MCP tools and LLMs authenticated by node cryptographic identity rather than static API keys.
  • Tailscale Serve & SSH: Securely exposes internal agentapi HTTP endpoints and terminal SSH access exclusively to machines within your tailnet.

Pillar 2: NATS JetStream Event Broker

  • Ultra-Lightweight Footprint: Single Go binary consuming under 20MB of RAM—runs easily alongside headless daemons on mini PCs.
  • At-Least-Once Delivery: Tasks in durable streams survive node reboots, daemon crashes, and network partitions.
  • Consumer Groups: Automatically load-balances tasks across multiple worker instances without manual IP mapping or single points of failure.

3. Step-by-Step Setup Guide

Step 1: Install & Connect Tailscale

# Run on all machines (dell5040, laptop, VPS)
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --ssh

Step 2: Launch NATS JetStream Server (Core VPS)

# Install and run NATS with JetStream persistence enabled
docker run -d --name nats-broker \
  -p 4222:4222 \
  -v /var/lib/nats:/data \
  nats:latest -js --sd /data

Step 3: Worker Consumer Bridge (Python + NATS.py)

Run this lightweight service on worker machines to consume tasks from NATS and feed them into agy agentapi:

# nats_agent_worker.py - Consumes tasks from NATS and triggers agy agentapi
import asyncio, json, subprocess
import nats
from nats.js.api import ConsumerConfig

async def main():
    nc = await nats.connect("nats://100.x.y.z:4222")  # Tailscale IP
    js = nc.jetstream()

    # Create stream if not exists
    await js.add_stream(name="TASKS", subjects=["tasks.dispatch.*"])

    # Pull subscriber with queue group
    sub = await js.pull_subscribe("tasks.dispatch.workers", "agent_worker_pool")

    print("NATS Agent Worker listening for tasks...")
    while True:
        try:
            msgs = await sub.fetch(batch=1, timeout=5)
            for msg in msgs:
                data = json.loads(msg.data.decode())
                prompt = data["prompt"]
                print(f"Received task: {prompt}")

                # Execute task via local agy agentapi
                res = subprocess.run(
                    ["agy", "agentapi", "new-conversation", "--model=flash", prompt],
                    capture_output=True, text=True
                )
                
                # Acknowledge task completion to NATS
                await msg.ack()
                print(f"Task dispatched: {res.stdout.strip()}")
        except asyncio.TimeoutError:
            pass

if __name__ == "__main__":
    asyncio.run(main())

4. Detailed Engineering Assessment

Advantages

  • Sub-Millisecond Wire Speed: Direct kernel-level WireGuard routing achieves <1ms latency on LANs.
  • High Reliability: NATS JetStream handles retries, message acknowledgments, and dead-letter queues.
  • Zero Public Ports: Complete isolation behind Tailscale cryptographic node identity.

Limitations

  • Infrastructure Setup: Requires running Tailscale on all hosts and managing a NATS daemon.
  • Worker Daemon: Requires running a small consumer bridge script to pipe NATS events into agentapi.
← Method 3 (MCP Bus) Next: Method 5 (Fleet Cockpits) →