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.