Pulse/docs/RELAY.md

Relay / Pulse Mobile Handoff (Relay and Above)

Pulse Relay provides end-to-end encrypted remote access foundations for Pulse instances. It allows secure remote connectivity without exposing your Pulse server to the public internet.

Supported Pulse Mobile clients pair from Settings → Remote Access using a QR code or deep link and connect through Pulse Relay over end-to-end encrypted remote access.

How It Works

┌──────────┐         ┌──────────────┐         ┌──────────┐
│  Pulse    │◄──E2E──►│  Relay       │◄──WSS──►│  Pulse   │
│  Mobile   │  ECDH   │  Server      │         │  Server  │
└──────────┘         └──────────────┘         └──────────┘

1. Your Pulse server maintains a persistent WebSocket connection to the relay server.
2. A mobile client connects to the relay server and authenticates.
3. An ECDH key exchange creates a per-channel encryption key.
4. Tunneled remote-access traffic is encrypted end-to-end — the relay server never sees plaintext data.

Quick Start

1. Go to Settings → Remote Access.
2. Toggle relay On.
3. Use the QR Code or Deep Link to pair a supported Pulse Mobile client.
4. Your paired mobile client connects through relay.

Requirements

• Relay, Pro, legacy Pro+, or Cloud license — relay is gated by the relay feature key.
• Outbound WebSocket — Pulse must be able to reach relay.pulserelay.pro (port 443).
• No inbound ports — you do not need to open any ports on your firewall.

Security

Relay was designed with a zero-trust model:

Property	Detail
Encryption	End-to-end ECDH key exchange per channel
Plaintext	Relay server never sees your monitoring data
Authentication	Per-session mobile authentication
Back-pressure	Data limiters prevent channel flooding
License-gated	Requires an active Relay-or-higher license
Configurable	Can be enabled/disabled at any time via Settings
Audit	Relay connection events are logged to the audit trail

Configuration

UI

Settings → Remote Access — toggle on/off, view QR code, and manage relay pairing sessions.

Environment Variables

For headless / container deployments, two env vars override the persisted relay.enc values at load time. Unset leaves the file value untouched.

Variable	Description	Default
PULSE_RELAY_ENABLED	Enable/disable relay (true/false/yes/no/1/0). Unrecognized values are ignored.	(unset)
PULSE_RELAY_SERVER	Override relay server URL. Must be ws:// or wss://. Invalid values are logged and ignored.	wss://relay.pulserelay.pro/ws/instance

Env vars take precedence over the file at load. Saving from the UI after an env override is active persists the env-effective state to disk, so clearing the env var alone will not revert the change — disable in the UI too.

Storage

Relay configuration is stored encrypted in relay.enc in the Pulse data directory.

API Reference

Method	Endpoint	Scope	Description
GET	/api/settings/relay	settings:read	Get relay status and config
PUT	/api/settings/relay	settings:write	Update relay settings
POST	/api/onboarding/qr	settings:read	Generate mobile onboarding QR code
POST	/api/onboarding/deep-link	settings:read	Generate mobile deep link

Pulse Mobile Pairing

iOS / Android

1. Pulse Mobile is in early access. Relay and Pro customers get install links from the authenticated download page.
2. Open Pulse Mobile and tap Connect to Server.
3. Scan the QR code from Settings → Remote Access in your Pulse web UI.
4. The app connects via the relay for push notifications and secure Open Pulse handoff.

Multiple Servers

Pulse Mobile can pair with multiple Pulse instances. Each pairing has its own encrypted channel.

Troubleshooting

Relay showing "Disconnected"

1. Confirm your Relay, Pro, grandfathered Pro+, or Cloud license is active (Settings → Plans & Billing).
2. Verify the Pulse server can reach the relay server:

   curl -s https://relay.pulserelay.pro/healthz
   

3. Check Pulse logs for relay errors:

   journalctl -u pulse | grep -i relay
   # or
   docker logs pulse | grep -i relay
   

Pulse Mobile can't connect

1. Verify relay is enabled in Settings → Remote Access.
2. Confirm your mobile account has beta access.
3. Re-scan the QR code — sessions can expire.
4. Ensure your mobile device has internet access.

Open Pulse handoff not loading

1. Check the relay connection status in Settings → Remote Access.
2. Look for WebSocket reconnection messages in Pulse logs.
3. Restart Pulse Mobile.

See Also

• Configuration Guide — environment variables
• Security — relay security details
• Plans & Entitlements — feature availability by plan