Setup guide

Connect OpenCode Mobile to your server

Three moves: start a password-protected opencode server, put the machine and phone on Tailscale, then save a Connection Profile in the app.

1 Start server Password + bind for remote 2 Tailscale Same tailnet, get a URL 3 Connect app Test, then save

The app does not create a tunnel or relay for you. You point it at a server you already run. Full server docs: opencode.ai/docs/server

1

Start the opencode server

On the machine that has your project

Run this in your project

Username defaults to opencode. Keep the process running while you use the phone.

cd /path/to/your/project
OPENCODE_SERVER_PASSWORD='choose-a-strong-password' \
  opencode serve --hostname 0.0.0.0 --port 4096

Important: Default bind is 127.0.0.1 — phones cannot reach that. Use --hostname 0.0.0.0 for Tailscale or LAN.

Sanity check on the machine

curl -u "opencode:${OPENCODE_SERVER_PASSWORD}" \
  http://127.0.0.1:4096/global/health

Healthy JSON with a version string means the server is up. Spec UI: http://127.0.0.1:4096/doc

Simulator / emulator URLs
TargetBase URL
iOS Simulator (same Mac)http://127.0.0.1:4096
Android emulatorhttp://10.0.2.2:4096
Physical phoneTailscale URL in step 2

Don’t expose plain public HTTP on the open internet.

2

Set up Tailscale

Phone and machine on one private network

Install and sign in

  1. Install Tailscale on the machine and the phone (download).
  2. Sign both into the same Tailscale account.
  3. Confirm both are online in the app or admin console.

Get the machine address

tailscale ip -4          # e.g. 100.x.y.z
tailscale status         # MagicDNS name

Either the 100.x IP or the MagicDNS name works once both devices are connected.

Recommended

Direct URL

With the server bound to 0.0.0.0, use:

http://100.x.y.z:4096

or http://my-mac….ts.net:4096

Optional

Tailscale Serve

Proxy localhost over HTTPS on the tailnet with tailscale serve 4096. Don’t use Funnel unless you want the public internet.

Check from the phone browser first

Open this while both devices are on Tailscale:

http://<machine-ip>:4096/global/health

Auth prompt or JSON = good. If it never loads, fix Tailscale before debugging the app.

Tailscale Serve commands 
# Terminal 1 — loopback is fine behind Serve
OPENCODE_SERVER_PASSWORD='…' \
  opencode serve --hostname 127.0.0.1 --port 4096

# Terminal 2
tailscale serve 4096

Use the HTTPS URL Tailscale prints. Needs HTTPS certs enabled for the tailnet. See Tailscale Serve.

3

Connect the app

Save one Connection Profile on the device

In OpenCode Mobile

  1. Open the app → Connect to server.
  2. Enter URL (from step 2), username opencode, and your password.
  3. Tap Test connection (calls GET /global/health).
  4. When it succeeds, tap Save.

Password is stored in Keychain / Keystore. Edit later in Settings → Server Connection.

If something fails
SymptomLikely cause
Unreachable / timeout Server down; still on 127.0.0.1; Tailscale offline; wrong IP/port
Authentication failed Wrong password or username
Works in simulator, not phone Phone needs Tailscale URL, not localhost
Android emulator can’t reach host Use http://10.0.2.2:4096
✓

Checklist

Printable mental model

  • OPENCODE_SERVER_PASSWORD set
  • opencode serve listening (0.0.0.0:4096, or loopback + Serve)
  • Tailscale connected on machine and phone
  • Health URL opens in the phone browser
  • App test succeeds, then Save

All docs · GitHub