Build Swarm Connectivity

The Arcturus-Prime build swarm spans 5 drones across 2 physical sites (Milky Way and Andromeda) totaling 66 cores and 140GB RAM. This doc explains how the pieces connect.

Fleet Layout

Milky Way Site (Local, 10.42.0.x)

Component	Host	LAN IP	Tailscale IP	Role
gateway-Altair	Altair-Link	10.42.0.199	100.64.0.234.88	Gateway + binhost registry (port 8090)
orch-Izar-Host	Proxmox Izar-Host	10.42.0.201	100.64.0.18	Primary orchestrator (port 8091)
drone-Izar-Host	Proxmox Izar-Host	10.42.0.203	100.64.0.126	16 cores, 11GB RAM (LXC)
drone-Tau-Host	Bare Metal	10.42.0.175	N/A	8 cores, 31GB RAM (LXC)
sweeper-Capella	Proxmox Izar-Host	—	—	8 cores, 31GB RAM (LXC)

Andromeda Site (Remote, 192.168.20.x)

Component	Host	Tailscale IP	Role
orch-Tarn-Host	Proxmox Tarn-Host CT 102	100.64.0.118	Secondary orchestrator
drone-Tarn	Proxmox Tarn-Host CT 103	100.64.0.91	14 cores, 12GB RAM (LXC)
drone-Meridian-Host	Meridian-Host (QEMU VM)	100.64.0.110	20 cores, 52GB RAM

Connection Architecture

Browser → Arcturus-Prime.com/api/gateway → CF Tunnel → Altair-Link:8090 (gateway)
                                                       ↓
                                              orchestrator discovery
                                              ↓                    ↓
                                    orch-Izar-Host (10.42.0.201)    orch-Tarn-Host (100.64.0.118)
                                        ↓                        ↓
                                  drone-Izar-Host (LAN)          drone-Tarn (Tailscale)
                                  drone-Tau-Host (LAN)     drone-Meridian-Host (Tailscale)
                                  sweeper-Capella (LAN)

Gateway Role

The gateway (Altair-Link:8090, exposed as gateway.Arcturus-Prime.com) is the single entry point:

• Build submission — receives package build requests and assigns them to orchestrators
• Binhost registry — serves compiled binary packages to all drones and the driver system
• Status aggregation — collects status from both orchestrators and presents a unified view
• Load balancing — distributes work across orchestrators based on drone availability

The Arcturus-Prime website proxies to the gateway via /api/gateway/[...path], which uses KV-backed caching for read-only requests in production.

Orchestrator Discovery

The /api/orchestrator proxy doesn’t hardcode an orchestrator IP. Instead:

1. On first request, it queries the gateway for the primary orchestrator URL
2. The result is cached for 60 seconds
3. If the primary is unreachable, it falls back to secondary
4. Each orchestrator manages the drones on its local site

This resilient discovery means the system tolerates orchestrator restarts and failovers without browser-side changes.

Cross-Site Communication via Tailscale

Drones on the Andromeda site cannot reach Milky Way LAN IPs directly (different subnet, different ISP). Tailscale provides the mesh:

• drone-Tarn (100.64.0.91) reports status to orch-Tarn-Host locally, which syncs with the gateway on Milky Way via Tailscale
• drone-Meridian-Host (100.64.0.110) similarly reports through orch-Tarn-Host
• The gateway on Altair-Link reaches orch-Tarn-Host via its Tailscale IP (100.64.0.118)
• Binary packages compiled on Andromeda drones are uploaded to the gateway binhost on Milky Way via Tailscale

Latency between sites is approximately 38ms, which is acceptable for build coordination traffic but means Andromeda drones have slightly higher package download times.

v3 vs v4 Control Planes

The swarm has two generations of API:

Version	Proxy Route	Backend	Notes
v3	/api/swarm	swarm.Arcturus-Prime.com (100.91.215.26:8100)	Original separate swarm API
v3 admin	/api/swarm-admin	swarm-admin.Arcturus-Prime.com (100.91.215.26:8093)	Direct orchestrator admin
v4	/api/gateway, /api/command	gateway.Arcturus-Prime.com (Altair-Link:8090)	Unified gateway combining gateway + orchestrator

Both v3 and v4 routes are active. The admin panel primarily uses v4 via /api/gateway and /api/command.

API Proxy Chain

A build submission from the admin panel follows this chain:

1. Browser calls POST /api/gateway/build/submit
2. Cloudflare Worker validates admin auth, forwards to gateway.Arcturus-Prime.com
3. Cloudflare Tunnel routes to Altair-Link:8090
4. Gateway selects an orchestrator and forwards the request
5. Orchestrator assigns work to available drones
6. Drone compiles the package and uploads the binary to the gateway binhost
7. Status updates flow back through the same chain via polling or SSE