HexaHost GameCloud Node Agent
Go daemon that runs on each game node. It maintains an outbound connection to the control plane, reports heartbeats and resource metrics, and executes signed lifecycle commands for Minecraft server containers.
Phase 0 scope
- Environment-based configuration loader
- Versioned JSON protocol message types (
agent.hello,agent.heartbeat,server.start, …) - Health endpoints (
/healthz,/readyz) - Main loop stub with graceful shutdown on
SIGINT/SIGTERM
Build
make build
make test
Configuration
| Variable | Required | Description |
|---|---|---|
NODE_ID |
yes | Unique node identifier |
NODE_AGENT_PUBLIC_URL |
yes | Control plane WebSocket URL |
NODE_TOKEN |
no* | Enrollment token (*required in production) |
NODE_AGENT_HEALTH_ADDR |
no | Health listen address (default :9100) |
NODE_HEARTBEAT_INTERVAL |
no | Heartbeat interval (default 10s) |
NODE_DATA_DIR |
no | Server data root (default /var/lib/hexahost-gamecloud) |
LOG_LEVEL |
no | Log level |
See repository root .env.example for the full variable list.
Protocol
Messages use a common envelope:
{
"protocolVersion": 1,
"messageId": "01...",
"type": "agent.heartbeat",
"timestamp": "2026-01-01T00:00:00Z",
"payload": {}
}
See internal/protocol/messages.go for all supported types.
Deployment
Production deployment uses systemd. See deploy/systemd/node-agent.service.