Live Map Relays & Gateways

Opening the Live Map on a phone, tablet, or web browser does not require you to know any relay address. SwapSanity automatically routes telemetry across native P2P mesh and discovered gateways.

This guide explains what is required if you or your club want to run a machine as a volunteer relay (such as a clubhouse laptop, venue timing station, or dedicated server).

Generic Relay Requirements

What you want to do…	Certificate Required?	Network & Port Requirements
Assist mobile field devices (Phones, rovers, wearables)	No (E2EE protected)	Zero setup. Uses a cryptographically secured zero-configuration mesh of devices and encrypted LAN UDP. Works completely offline.
Relay on local venue Wi‑Fi (Screens/LAN devices)	No (E2EE protected)	A standard port (e.g. `8080`) over local Wi‑Fi is sufficient.
Serve Web Spectators & PWAs (Web browsers and Progressive Web Apps)	Yes (Valid TLS cert from a trusted CA like Let’s Encrypt)	Must be reachable on a TLS port (typically port 443, or custom TLS ports like `8443`). Requires IPv6 firewall permission or IPv4 router port forwarding.

Why Web Browsers & PWAs Require TLS & Routed Ports

The SwapSanity web app and Progressive Web Apps (PWAs) are delivered over HTTPS (https://app.swapsanity.com).

Browser Security (Mixed-Content Rules): Modern web browsers strictly block unencrypted ws:// connections originating from HTTPS pages. Web spectators can only connect to secure wss:// endpoints.
Valid CA Certificate: The certificate must be issued by a recognized Certificate Authority (such as Let’s Encrypt) matching the public DNS hostname.
Port Routing:
- IPv6: Modern connections with globally routable IPv6 addresses only require permitting incoming TCP traffic on the selected port (typically 443 or 8443) in your firewall rules (no NAT translation needed).
- IPv4: Traditional residential/venue IPv4 connections require configuring Port Forwarding on your router to forward external port 443 (or 8443) to the relay machine’s local IP address.

Public vs campus ports (demos and phones)

Internet browsers and phones off the venue Wi‑Fi should use a relay on TCP 443 (wss://your.host/mesh-stream). A sandbox helper on :8433 (or :80) often works on campus Wi‑Fi and fails on LTE / off-site firewalls. SwapSanity’s public spectator URL is wss://pilot.ceas.wmich.edu/mesh-stream (port 443).

Connecting to that WebSocket does not log you in. Live map dots still only decrypt for members of that group. Demo GPS bots (make demo-record) therefore run a logged-in CLI in the same group and send on Iroh plus that public WSS. Operator details: repo conductor/tracks/monetization_gates_validation_20260904/demo_videos.md.

Three roles at a venue (pick one per computer)

Do not run the tent radio and the Flutter desktop map on the same laptop. They both want UDP port 53535 and an Iroh node.

Role	What to run	Iroh?
Tent radio	`swapsanity_cli edge-relay` (optional `--wss --opt-in --port 8080`)	Yes — this process is the Iroh peer
Operator map	Flutter desktop app (Share + live map)	Yes — participant, not a WSS fan-out
Kiosk / TV	Browser at `http://<tent-laptop>:8080` (LAN) or `wss://` on 443	No. WSS spectator only

Internet is optional. Phones on the same Wi‑Fi still share GPS over LAN UDP. Without WAN, the public website will not update.

LAN kiosk files: copy a Flutter web build, then serve it from the same port as WSS (same origin ws://):

make tent-web-sandbox
swapsanity_cli edge-relay --wss --opt-in --port 8080 --serve-web ~/.swapsanity/tent-web

GET / is the app, GET /relay is JSON status, WebSocket stays /mesh-stream. No COOP/COEP headers. Google sign-in needs https — http:// clubhouse TVs are spectator/map only.

Linux tent hotspot (--wifi-ap --opt-in): NetworkManager nmcli creates SSID SwapSanity (or --wifi-ssid). Client isolation is off so phones can UDP to each other. --wifi-ap-dry-run prints the commands without touching the radio. Tear-down is on Ctrl-C. macOS/Windows: make a hotspot yourself. Without internet, phones on that Wi‑Fi still share GPS; the public website will not update.

If Flutter desktop and edge-relay both try UDP 53535, the second process logs tent radio already running.

Running a Relay via CLI (`swapsanity_cli`)

1. Join the group mesh (default)

Logged-in CLI joins Iroh gossip (and LAN UDP) for your groups. It does not open a WebSocket port:

swapsanity_cli edge-relay
swapsanity_cli edge-relay --group-id YOUR_GROUP --event-id YOUR_EVENT

2. Host a spectator WSS gateway (explicit)

LAN screens or internet browsers need --wss (and --opt-in on a powered machine):

swapsanity_cli edge-relay --wss --opt-in --port 8080
swapsanity_cli edge-relay --wss --opt-in --port 8080 --serve-web ~/.swapsanity/tent-web

Encrypted telemetry logs land under ~/.swapsanity/mesh_blackbox/groups/{id}/ as authenticated SSMH (mesh_hearsay.dat) envelopes (and events/{id}/ when you pass --event-id). After the session, fuse RSSI-weighted tracks and optionally upload:

swapsanity_cli mesh-reconstruct --group-id YOUR_GROUP
swapsanity_cli mesh-reconstruct --group-id YOUR_GROUP --upload

That writes reconstructed/tracks.json plus per-tag .fit files next to the logs, then (with --upload) stores them for group members. Marking reconstructed and uploaded makes the local logs deletable (mesh-log-mark). If several laptops logged the same group, union them first:

swapsanity_cli mesh-log-merge --group-id YOUR_GROUP --from dir1 --from dir2

3. Public / Dedicated Web Relay (Port 443 + TLS)

For an always-on server or laptop with a domain and Let’s Encrypt certificate:

swapsanity_cli edge-relay \
  --wss --public-relay --opt-in \
  --port 443 \
  --tls-cert /etc/letsencrypt/live/your.host/fullchain.pem \
  --tls-key /etc/letsencrypt/live/your.host/privkey.pem \
  --announce-url wss://your.host/mesh-stream

--wss: Bind the spectator WebSocket (off unless you pass this flag).
--public-relay: Also forward groups you do not belong to (requires --wss and --announce-url).
--announce-url: The public wss:// address advertised to spectators (must match the TLS certificate).

End-to-End Security & Privacy

All live GPS telemetry in SwapSanity is encrypted end-to-end with AES-256-GCM and authenticated with a 16-byte cryptographic tag.

Relays (even public relays you do not own) operate strictly as zero-knowledge packet forwarders: - Relays cannot read member coordinates. - Relays cannot forge or spoof fake locations (they lack the group DEK). - Any tampering with ciphertext frames causes receiving devices to immediately drop the invalid packet.