Skip to content

Phone can't reach Pluma

You're running Pluma on a laptop / desktop, you've typed the URL into your phone's browser, and you get a connection error or it just spins forever.

Walk down this list; the first hit is usually the problem.

1. Bound to loopback only?

Most common cause. If Pluma is listening on 127.0.0.1:8787 (or localhost:8787), only the host machine can reach it. Your phone — even on the same WiFi — can't.

Check what Pluma is actually bound to:

lsof -iTCP -sTCP:LISTEN -P -n | grep pluma

Get-NetTCPConnection -State Listen | Where-Object OwningProcess -in (Get-Process pluma).Id

If you see 127.0.0.1:8787 or localhost:8787 — that's loopback. Restart with :8787 (binds all interfaces) or 0.0.0.0:8787 (explicit):

./pluma -addr :8787

Or set it in config.toml:

listen = ":8787"

2. Same WiFi?

Check the host's IP:

ipconfig getifaddr en0

ip addr show

Get-NetIPAddress -AddressFamily IPv4 | Where-Object PrefixOrigin -eq 'Dhcp'

From your phone, hit http://<that-ip>:8787. Phone has to be on the same subnet — corporate WiFi often segregates devices.

3. Firewall in the way?

The OS firewall might block incoming connections to a freshly-built binary.

System Settings → Network → Firewall → Options. Make sure pluma is in the list set to "Allow incoming connections", or toggle the firewall off for the test run.

sudo ufw allow 8787/tcp

Windows Defender → Allow an app through firewall → Change settings → Allow another app → browse to pluma.exe. Tick both Private and Public.

4. allowed_hosts set?

If you've configured the host allowlist in config.toml, requests from your phone's hostname / IP get rejected unless they match.

Check config.toml:

allowed_hosts = [
  "192.168.1.0/24",        # your LAN subnet — phone needs to be inside this
]

Empty list = open. The simplest fix while debugging is to comment the entry out, restart, and re-confirm reachability before re-adding it.

5. Auth gate blocking?

If require_auth = true and no passkey is enrolled at the phone's origin, the phone might be hitting the Pair screen and not realising it.

Open http://<host-ip>:8787 on the phone. You should see either Pluma's UI or the Pair prompt. If it's the Pair prompt, enrol a passkey. If you're getting a blank page or a 401, check the server log — it'll say which middleware refused.

6. The longer-term fix: Tailscale

If you want to reach Pluma from anywhere your phone has internet (not just the same WiFi), use the embedded Tailscale node:

tsnet_enabled = true
tsnet_hostname = "pluma"

You get https://pluma.<tailnet>.ts.net/ with magic-cert HTTPS, no port forwarding, no firewall holes, and the connection works on cellular too. Full walkthrough: Multi-device access (Tailscale).