HydraNode

Universal node agent. Runs on Windows render nodes, Raspberry Pis, and Quest headsets. Phones home to HydraCluster, reports status, and auto-provisions software.

Infrastructure


Runs on	Windows render nodes, Raspberry Pi, Quest headsets
Server	N/A (agent, not a server)
Binary (Windows)	`C:\hydranode\hydranode.exe`
Binary (Linux)	`/usr/local/bin/hydranode`
Config (Windows)	`C:\Windows\System32\config\systemprofile\.hydranode\config.yaml`
Config (Linux)	`/root/.hydranode/config.yaml`
Service (Windows)	`schtasks /query /tn HydraNode`
Service (Linux)	`systemctl status hydranode`
Logs (Windows)	`C:\Windows\System32\config\systemprofile\.hydranode\hydranode.log`
Logs (Linux)	`journalctl -u hydranode -f`
Release	`https://releases.experiencenet.com/hydranode/production/latest.json`

Operations

Check agent status (via HydraCluster)

Nodes are managed through HydraCluster. Check node status:

curl -s -H "Authorization: Bearer <token>" https://hydracluster.experiencenet.com/api/v1/nodes | python3 -m json.tool

Or use the web dashboard: https://hydracluster.experiencenet.com/admin

Install on Windows

Open https://hydracluster.experiencenet.com/enroll on the machine
Fill in name, set owner, submit
Copy the PowerShell install command and run as Admin
The node goes online in the dashboard

Install on Linux (Pi / Quest)

Open https://hydracluster.experiencenet.com/enroll on the machine
Follow the bash install instructions
The agent installs to /usr/local/bin/hydranode and registers as a systemd service

Restart agent (Windows)

schtasks /End /TN HydraNode
Start-Sleep 3
schtasks /Run /TN HydraNode

Restart agent (Linux)

systemctl restart hydranode

Force update

The agent auto-updates from releases.experiencenet.com every 6 hours. To force:

Windows:

Invoke-WebRequest -Uri 'https://releases.experiencenet.com/hydranode/production/latest/hydranode-windows-amd64.exe' -OutFile C:\hydranode\hydranode-new.exe
schtasks /End /TN HydraNode
Start-Sleep 3
Copy-Item C:\hydranode\hydranode-new.exe C:\hydranode\hydranode.exe -Force
Remove-Item C:\hydranode\hydranode-new.exe
C:\hydranode\hydranode.exe install
schtasks /Run /TN HydraNode

Linux:

echo yes | hydranode update

Key Concepts

Enrollment flow

Machine visits /enroll on HydraCluster
Server creates a pending node entry, provides install script
Agent installs, gets enrollment token
First heartbeat transitions node to online
Admin assigns role (render-node, pi, quest) and venue

Heartbeat

The agent sends a heartbeat to HydraCluster every 30 seconds, reporting:

Agent version
OS info
Provider status (LarkXR running, port checks)
Network info

Provisioning (render nodes)

When a node is assigned the render-node role, the agent:

Downloads the LarkXR package from the release server
Extracts and installs (MySQL, VC++ runtime, DirectX)
Starts the LarkXR Launcher in the user's desktop session
Reports provider status via heartbeat

Key paths (Windows)

Path	Purpose
`C:\hydranode\hydranode.exe`	Agent binary
`C:\hydranode\enroll.yaml`	Enrollment token
`C:\Windows\System32\config\systemprofile\.hydranode\`	SYSTEM profile data dir
`C:\LarkXR\larkxr-standalone\`	LarkXR installation

Troubleshooting

Node offline in dashboard

Check if the scheduled task is running (Windows):
```
schtasks /query /tn HydraNode
```

Check if it can reach HydraCluster:

Invoke-WebRequest -Uri 'https://hydracluster.experiencenet.com/api/v1/health' -UseBasicParsing

Check agent logs for errors

LarkXR not starting

Verify a user is logged in (LarkXR needs a desktop session)
Check ports: netstat -an | Select-String '8181|8282|13306'
Check LarkXR logs at C:\LarkXR\larkxr-standalone\log\

Agent won't install

Check that the machine has network access to both hydracluster.experiencenet.com and releases.experiencenet.com. If behind a VPN, ensure WireGuard tunnel is active.

HydraPipeline