WebSocket Protocol
How the hub and node communicate
The hub and node communicate over a persistent WebSocket connection. This enables real-time command dispatch and progress streaming.
Connection Flow
- Node requests a short-lived WS token from
POST /api/v1/nodes/:id/ws-token - Token is valid for 60 seconds
- Node connects to
ws://hub:4865/api/v1/ws?token=<ws-token> - Connection established — node is marked as “online”
Keepalive
- The node sends a ping every 30 seconds
- The hub must respond with a pong within 90 seconds
- If the hub does not respond, the node disconnects and reconnects
Auto-Reconnect
If the connection drops, the node reconnects with exponential backoff:
- Start at 1 second delay
- Double after each failed attempt
- Maximum delay: 60 seconds
- Reset to 1 second after successful reconnection
Commands
The hub sends JSON-encoded commands over the WebSocket:
| Command | Description |
|---|---|
Backup | Run a backup with specified plan configuration |
Restore | Restore files from a snapshot |
Prune | Run repository maintenance (prune) |
Check | Verify repository integrity |
RepoStats | Collect repository storage statistics |
ListSnapshots | List snapshots in a repository |
BrowseSnapshot | List files in a snapshot path |
Update | Self-update the node agent |
Uninstall | Remove the node agent |
Token Rotation
WebSocket tokens are short-lived (60 seconds) and single-use. The node must request a new token before each connection attempt. This limits the window of exposure if a token is intercepted.