# Monitor Server Connector Plan

## Current design

The plugin and Monitor communicate over a local bridge port (`monitor_port` / `MONITOR_PORT`).

### Data flow

1. **Monitor → Plugin** (GET): Plugin queries `GET /telemetry` on the bridge for host hardware data.
2. **Plugin → Monitor** (POST): Plugin pushes OpenClaw metadata via `POST /openclaw` to the bridge.
3. **Monitor → Backend**: Monitor heartbeats to `POST /monitor/server/heartbeat-v2` with `X-API-Key`, enriched with any available OpenClaw metadata.

### Bridge endpoints (on Monitor, 127.0.0.1:MONITOR_PORT)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check, returns monitor version and identifier |
| `/telemetry` | GET | Latest hardware telemetry snapshot |
| `/openclaw` | POST | Receive OpenClaw metadata from plugin |

### Plugin behavior

- On `gateway_start`, plugin begins periodic metadata push (aligned with `reportIntervalSec`).
- Initial push is delayed 2s to allow Monitor bridge startup.
- If bridge is unreachable, pushes fail silently. Plugin remains fully functional.
- On `gateway_stop`, periodic push is stopped.

## No longer used

The following design has been retired:

- challenge UUID / RSA handshake / WebSocket telemetry
- Plugin-side `server/` sidecar process

## Heartbeat payload

```json
{
  "identifier": "vps.t1",
  "openclaw_version": "OpenClaw 2026.3.13 (61d171a)",
  "plugin_version": "0.2.0",
  "agents": [],
  "cpu_pct": 10.5,
  "mem_pct": 52.1,
  "disk_pct": 81.0,
  "swap_pct": 0.0,
  "load_avg": [0.12, 0.09, 0.03],
  "uptime_seconds": 12345,
  "nginx_installed": true,
  "nginx_sites": ["default"]
}
```

`openclaw_version`, `plugin_version`, and `agents` are optional enrichment from the plugin. If plugin never pushes metadata, these fields are omitted and the heartbeat contains only hardware telemetry.