initial commit

apps/node-agent/README.md

@@ -0,0 +1,51 @@
+# 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
+
+```bash
+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:
+
+```json
+{
+  "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`.