vrr/Pulse
2
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-10-19 10:33:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13
Pulse/docs/RELAY.md
rcourtman 8a99b16d6c docs: correct customer docs that drifted from the source 
Audited the customer-facing docs against the code: about 5,200 concrete
claims (env vars, endpoints, flags, defaults, ports, UI labels), plus every
environment variable the code reads. Each discrepancy was re-verified
against the source before editing, and every edit was reviewed again.

What users would have hit following the old text:
- UI paths and labels that no longer exist (Settings > Relay, Platform
  connections, Access Control, SSO Providers, Create Organization) and
  Patrol mode names (now Ask first, Safe auto-fix, Autopilot).
- Wrong values and behaviour: LOG_MAX_AGE=0 does not disable cleanup,
  Patrol evidence budget is 10 calls and 12 turns, ALLOW_UNPROTECTED_EXPORT
  covers private networks too, PULSE_AUDIT_ASYNC defaults on.
- Agent install: install.sh ignores PULSE_ENABLE_KUBERNETES and
  PULSE_ENABLE_PROXMOX, rejects --disable-auto-update, and the token
  fallback lives in the state directory.
- API: audit endpoints answer 402 on Community, onboarding QR is GET,
  type=container is rejected, several routes need admin plus a scope.
- HTTP_REDIRECT_PORT was not documented anywhere.

Docs are mirrored under frontend-modern/public/docs, so each change is
applied to both copies. The tests that pinned the old wording (including
three that asserted claims the code contradicts) are updated alongside.

Contract-Neutral: Customer docs corrected to match shipped behaviour; no runtime, API or contract change.
2026-10-11 13:59:56 +01:00

5.6 KiB
Raw Blame History

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 Pulse Mobile relay access token creation is recorded in the audit trail. Relay connection events are written to the Pulse server log.

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
GET /api/onboarding/qr settings:read Generate mobile onboarding QR code
GET /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