Body Provisioning

This document describes how a Body (GPU render node) gets provisioned with a WireGuard tunnel to the district server, making it reachable from any Head in the mesh.

Enrollment Flow

sequenceDiagram
    participant BM as Body Machine
    participant HC as HydraCluster
    participant HG as HydraGuard Hub

    BM->>HC: 1. Enroll (browser)
    HC->>HC: 2. Create node (pending)
    HC-->>BM: 3. Install script with token
    BM->>BM: 4. Install hydranode
    BM->>HC: 5. Heartbeat (token)
    HC->>HC: 6. Node online
    HC->>HG: 7. Provision WireGuard (API call)
    HG-->>HC: 8. Assign Air peer 10.10.100.x + config
    HC-->>BM: 9. Return WireGuard config
    BM->>BM: Apply WireGuard config
    BM->>HG: 10. WireGuard tunnel active

Step by Step

1. Self-Enrollment

A technician opens the HydraCluster enrollment page (/enroll) on the Body machine's browser and fills in:

• Node name
• Owner
• District
• Venue

HydraCluster creates the node in pending status and generates a unique bearer token.

2. Install Script

The technician downloads the install script from HydraCluster. The script contains:

• The HydraNode agent binary download URL
• The unique bearer token for this node

3. HydraNode Installation

The install script downloads and installs HydraNode, which:

• Saves the token to enroll.yaml
• Registers as a systemd service
• Starts sending heartbeats to HydraCluster

4. First Heartbeat

On the first heartbeat, HydraCluster transitions the node from pending to online and records:

• IP address
• Hostname
• OS version
• Node agent version
• Docker status

5. WireGuard Provisioning

When the node's roles include WireGuard, HydraCluster calls the HydraGuard API:

For standalone Bodies (Air peers):

• POST /api/v1/air/provision to HydraGuard
• HydraGuard assigns the next available address in the 10.10.100.x range
• Returns a complete WireGuard config file

For venue gateway Bodies:

• POST /api/v1/gateway/provision to HydraGuard
• Derives the LAN subnet from the node's IP
• Returns a gateway WireGuard config with IP forwarding and masquerade rules

6. WireGuard Activation

The WireGuard config is applied on the Body:

• Config written to /etc/wireguard/wg0.conf
• Interface brought up with wg-quick up wg0
• Persistent keepalive ensures NAT traversal

The Body is now reachable from any point in the WireGuard mesh via its assigned address (e.g., 10.10.100.42).

7. Dual IP Registration

HydraCluster stores both IPs for the Body:

Both IPs are served to Heads as stream_url (WireGuard) and stream_url_lan (LAN).

Streaming Software

After WireGuard is active, HydraNode also provisions the streaming software:

1. Sunshine -- NVIDIA GPU streaming server (Moonlight protocol compatible)

   • Installed at C:\Sunshine (Windows Bodies)
   • Health port: 47990 (TCP)
   • Encryption disabled for LAN-only operation
   • System tray disabled (headless render nodes)

2. HydraBody -- Experience launcher service

   • Port: 47991
   • Launches/stops experiences on demand
   • Managed by HydraCluster

Post-Provisioning

Once provisioned, the Body:

• Maintains its WireGuard tunnel with persistent keepalive (25s)
• Sends heartbeats to HydraCluster every 30 seconds
• Reports health metrics (GPU usage, VRAM, stream count)
• Auto-updates via releases.experiencenet.com every 6 hours
• Is reachable from both the local LAN and the WireGuard mesh