Pulse/docs/RELAY.md

Relay / Pulse Mobile

Pulse Mobile is being retired on 31 March 2027. Paired phones keep working until then. Relay is no longer sold as a plan; existing Relay subscribers have Pro features at their current price. For alerts on your phone afterwards, add an ntfy, Gotify, or Pushover destination under Alerts, and reach the Pulse web UI away from home through your own VPN or tunnel.

Pulse Relay is the end-to-end encrypted connection between a Pulse instance and paired Pulse Mobile devices. It lets the app reach your server without exposing it to the public internet. It does not provide remote access to the Pulse web UI.

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

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 → Pulse Mobile.
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 → Pulse Mobile — 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 → Pulse Mobile 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 → Pulse Mobile.
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 → Pulse Mobile.
2. Look for WebSocket reconnection messages in Pulse logs.
3. Restart Pulse Mobile.

See Also

• Configuration Guide — environment variables
• Security — security for existing paired phones
• Plans & Entitlements — feature availability by plan