Running the Relay Service
The relay service (hone-relay) provides real-time cross-device synchronization via WebSocket. It manages rooms, buffers messages for reconnecting devices, and persists deltas to SQLite.
Configuration
Create relay.conf in the working directory:
host=0.0.0.0
port=8443
auth.secret=<shared-secret>
| Key | Required | Description |
|---|---|---|
host | No | Bind address (default: 0.0.0.0) |
port | No | HTTP port (default: 8443) |
auth.secret | No | Shared secret for token validation. Must match auth service’s AUTH_SECRET. |
Ports
| Port | Protocol | Purpose |
|---|---|---|
| 8443 | HTTP | REST API, health checks |
| 8444 | WebSocket | Real-time sync connections |
Running
cd /opt/hone-relay && ./hone-relay
The service reads relay.conf from its working directory.
Development Mode
Leave auth.secret empty or omit it entirely to disable token validation. All connections will be accepted without authentication. This is useful for local development.
host=127.0.0.1
port=8443
auth.secret=
Sync Protocol
Devices connect via WebSocket and join rooms identified by project ID. The relay:
- Authenticates the device token against the shared secret (or skips in dev mode).
- Assigns the connection to a project room.
- Forwards deltas from any device in the room to all other devices.
- Persists deltas to SQLite for offline reconciliation.
- Buffers messages for 60 seconds for devices that temporarily disconnect.
Message Buffering
When a device disconnects, the relay holds its pending messages for 60 seconds. If the device reconnects within that window, it receives the buffered messages and resumes without data loss. After 60 seconds, the buffer is dropped and the device must do a full reconciliation from SQLite on reconnect.
Rate Limiting
Rate limiting is per-connection with configurable windows. Under default settings, a single device can send up to 100 messages per second. This is sufficient for real-time typing sync without overwhelming other devices in the room.
SQLite Persistence
Deltas are stored in a local SQLite database (relay.db in the working directory). This provides:
- Offline reconciliation: Devices that were offline for longer than the 60-second buffer window can catch up from persisted deltas.
- Audit trail: All changes are recorded with timestamps and device IDs.
The database file is created automatically on first startup.
Tests
cd hone-relay && bun test
Runs 48 tests covering auth, buffer management, WebSocket hub, and configuration parsing.