OpenCode Mobile won't connect? Here's how to fix it

First, the 30-second checklist:

1. On your machine: opencode serve --hostname 0.0.0.0 --port 4096 (bind 0.0.0.0, not 127.0.0.1, so other devices can reach it).
2. From the phone's browser, open http://<host>:4096/global/health — you should see {"healthy":true}.
3. In the app, use the full URL including http:// and the port, e.g. http://100.108.64.76:4096.

New here? Start with the setup guide.

“The server URL could not be parsed” (malformed URL)

Symptom: the app rejects the address before even trying to connect.

Include the scheme and port: http://192.168.1.50:4096, not 192.168.1.50 or opencode://…. Remove stray spaces, quotes, or a trailing slash path. Use http:// for a plain local/Tailscale server and https:// only if you put a real TLS certificate in front of it.

“No working internet/network” (no internet)

Symptom: even a public connectivity check fails.

The phone has no usable network. Toggle Wi-Fi/mobile data, and if you connect over a VPN, confirm Tailscale (or your VPN) is connected on the phone. Re-open the app after the network is back.

“TLS/certificate problem” (TLS error)

Symptom: the handshake fails on an https:// URL.

Either switch to http:// (fine for a private LAN/Tailscale link), or fix the server certificate so it's valid and trusted by Android. Self-signed certs will fail unless the cert is installed on the device.

“Server reachable but /global/health failed” (health failed)

Symptom: the host answers, but the health endpoint returns an error.

Usually the wrong path, authentication, or an old server. Confirm the port is the one opencode serve is listening on, update opencode (npm i -g opencode-ai@latest), and if you set OPENCODE_SERVER_PASSWORD, enter the matching username/password in the app.

“Connection timed out” (timeout)

Symptom: the connection hangs and is dropped, not refused.

Something is silently blocking the packets — a firewall, the wrong port, or a Tailscale ACL that doesn't allow your phone to reach the host. Open the port on the host firewall and check your tailnet ACLs permit the device.

“Server is unreachable” (server unreachable)

Symptom: internet works, but nothing answers at the host:port.

• Confirm opencode serve is actually running and bound to 0.0.0.0.
• Confirm the phone is on the same tailnet/LAN as the host.
• If you used a hostname and it doesn't resolve, MagicDNS may be off — use the raw Tailscale IP (e.g. http://100.x.y.z:4096).
• Double-check the port matches the server.