# 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`.