How panel and Beacon talk

Signed HTTP commands, websocket streams, and the auth that separates them.

Repository-validated operator guidance View source ↗

#Commands are HTTP

Every Beacon command — create, install, power, files, backups, transfers, compose, database, build — is a signed HTTP request carrying timestamp, nonce, and HMAC signature with replay protection. Timeouts fit the work: 30 seconds by default, 5 minutes for creates that pull images, 15 minutes for transfers. Only idempotent reads and the power route retry; every other mutation is attempted once. Non-loopback Beacon URLs must be HTTPS with TLS 1.2 or better.

FLOW

Panel to Beacon

01Sign commandHMAC

02HTTP to Beaconrun

03Executewebsocket

04Stream back/api/remote

05Report observation

#Streams are websockets

Console, stats, logs, backup progress, and install output stream over websockets on short-lived scoped tokens (websockets: 2 minutes, one-time redemption). Beacon never accepts commands over a socket, and install streams additionally require admin scope. The panel mints 90-second tokens and proxies browser sockets to Beacon.

Two credential worlds

User JWTs never work on /api/remote, and node tokens never work on user routes. Beacon webhooks to the panel use the node token; user sessions use the HttpOnly cookie plus CSRF binding. Mixing them fails closed.

#Beacon surface

Beacon :9090 (node HMAC unless noted)

POST /servers  DELETE /servers/{id}  POST .../power{signal}
GET|PUT .../configuration   POST .../install|/reinstall
POST|GET .../backups  .../backups/restore  .../backups/download
GET|POST|PUT|DELETE .../files...   (host filesystem)
POST /compose/deploy  .../{stackId}/stop|start|restart|pull
POST /database/provision|backup|restore
POST /build/dockerfile|nixpacks   GET /build/logs|status
GET /api/system  /api/capabilities   /v1/host/info|disk|memory
GET /health (public)  GET /metrics (loopback or bearer)