Troubleshooting

Install & run PME Edge

Symptoms: Binary won't start, agent UI unreachable, WireGuard interface missing.

1. Confirm the binary is executable: chmod +x edge
2. Run edge run — default agent UI at http://127.0.0.1:9191
3. macOS: Gatekeeper — xattr -d com.apple.quarantine edge. WireGuard/pf need one-time sudoers — see macOS install
4. Ubuntu: Install wireguard-tools / dnsmasq; set VPN_LAN_INTERFACE to your NIC; use systemd caps if Operation not permitted — see Ubuntu install
5. Wrong arch binary (arm64 vs amd64) — re-download the matching release asset
6. Run edge doctor for platform checks

Register with PME

Symptoms: Edge UI shows not registered; PME setup step stays pending.

1. Registration happens in the PME Edge local UI (127.0.0.1:9191), not only the hosted console
2. Use the same email/password as your hosted PME account
3. Tap Register with PME Server — confirm control stream connected in logs
4. After register, confirm the agent appears linked in PME #/setup

PME Relay (Mesh Pro)

Symptoms: Invitees on cellular cannot connect; Edge shows relay disabled or disconnected.

1. New accounts include a 30-day relay trial — no upgrade required to start
2. Start Edge with PME_RELAY_ENABLED=true (shell env, or /etc/default/edge when using systemd)
3. Restart Edge and confirm the dashboard shows relay connected
4. Re-create or reprovision the invite so the WireGuard config uses the relay endpoint
5. Test from cellular — home Wi‑Fi often bypasses the remote path

Edge still uses outbound WSS only — no inbound firewall hole for registration or relay.

Control stream offline

Symptoms: Edge registered but PME shows stream offline; invites cannot provision WireGuard.

1. Verify Edge can reach PME_SERVER_URL over HTTPS outbound
2. Check Edge logs for control stream dial errors
3. Re-register from Edge UI if node credentials were cleared
4. No inbound firewall hole required — agent uses outbound WebSocket only

First invite

Symptoms: Cannot create invite, invitee stuck on VPN setup, cannot reach shared IP.

1. Create invite from PME Edge UI → Invitations
2. Set Allowed IPs to the device or subnet you want to share
3. Invite link format: hosted PME #/login?vpn_invite=<id>
4. Invitee completes WireGuard on the PME console after accepting
5. Free tier: 1 active invite — delete old invites or upgrade in PME billing

DNS on iPhone

Symptoms: WireGuard shows “DNS resolution failure” immediately on cellular.

1. VPN_ENDPOINT must be an IP or resolvable hostname — not a LAN-only name
2. If DNS in the tunnel config is LAN-only (e.g. 192.168.x.1), iOS cannot resolve the endpoint before the tunnel is up
3. Use public DNS or split-tunnel with IP endpoint; reprovision invite after changing config