HydraHead Runbook

Head device registry for kiosks, VR headsets, and tablets.

Infrastructure

Overview

HydraHead manages head device registration. Head devices are kiosk/display endpoints that receive streams from render nodes (Hydra Bodies) via Sunshine/Moonlight. This is a light service focused on tracking which devices are available, where they are assigned, and how they are configured for streaming.

Streaming architecture:

• Body (render node): Runs Sunshine + UE application, streams via NVENC
• Head (display node): Runs hydraheadwindows + Moonlight, receives the stream
• HydraHead (this service): Central registry that both body and head agents poll for config

API

Admin token is in /root/.hydrahead/config.yaml on the server.

# List all heads
curl https://hydrahead.experiencenet.com/api/v1/heads

# Get a specific head
curl https://hydrahead.experiencenet.com/api/v1/heads/<id>

# Create a head (auth required)
curl -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"id":"my-kiosk","name":"My Kiosk","type":"kiosk","district":"bxl1","venue":"test","stream":{"stream_url":"<body-ip>","stream_app_id":"<app-name>"}}' \
  https://hydrahead.experiencenet.com/api/v1/heads

# Update a head (auth required)
curl -X PUT -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name":"My Kiosk","type":"kiosk","district":"bxl1","venue":"test","stream":{"stream_url":"<body-ip>","stream_app_id":"<app-name>"},"status":"enrolled"}' \
  https://hydrahead.experiencenet.com/api/v1/heads/<id>

# Health check
curl https://hydrahead.experiencenet.com/api/v1/health

Key Concepts

• Head types: kiosk (standalone display), vr_headset (VR headset), tablet (mobile touchscreen)
• District/venue: Each head belongs to a district+venue; the body in the same district streams to it
• Stream config: stream_url = body's IP, stream_app_id = Sunshine app name (must match apps.json on the body)
• YAML store: All device state is stored in YAML files under the config directory (no database)
• Provider config: Streaming provider (sunshine/larkxr) is configured per district in HydraCluster's config.yaml under providers:

Troubleshooting

Head not connecting to stream

1. Verify the head is registered: curl https://hydrahead.experiencenet.com/api/v1/heads
2. Check district/venue matches the body's district/venue
3. Verify Sunshine is running on the body: tasklist /FI "IMAGENAME eq sunshine.exe"
4. Verify the app is registered in Sunshine: curl -k -u sunshine:sunshine https://<body-ip>:47990/api/apps
5. Check Moonlight is running on the head: tasklist /FI "IMAGENAME eq Moonlight*"
6. Check hydraheadwindows logs: Get-Content C:\WINDOWS\system32\config\systemprofile\.hydraheadwindows\hydraheadwindows.log -Tail 50
7. Check Sunshine logs on the body: Get-Content C:\Sunshine\config\sunshine.log -Tail 50
8. Verify network connectivity between head and body (same LAN, ports 47984/47989/47990 accessible)

Stale Moonlight processes

If hydraheadwindows detects Moonlight as "running" but streaming isn't working, kill stale processes:

taskkill /F /IM Moonlight.exe

hydraheadwindows will relaunch Moonlight on its next tick (30s interval).

Pairing issues

Moonlight must be paired with Sunshine before streaming. hydraheadwindows handles this automatically. If pairing fails, check C:\WINDOWS\system32\config\systemprofile\.hydraheadwindows\pairing.yaml and delete it to force re-pairing.