Setup guide

Connect OpenCode Mobile to your server

The phone talks to an opencode server on your computer. In the app, tap Connect to server, then pick a way in. The app detects API v1 or API v2 from whatever answers.

1 Remote QR OpenCode tunnel, then scan 2 Same Wi-Fi QR Pair on the local network 3 Host and password Username and password you set 4 Pairing code Same link, no camera

You run the server. opencode pair --remote opens OpenCode's tunnel. The phone only joins it. OpenCode 1 server reference: opencode.ai/docs/server. OpenCode 2 pairing: opencode.ai/v2/docs/cli/web.

API

Which API

The app picks this after the server answers

OpenCode 1

API v1

Start it with opencode serve. Connect with a host, username, and password. There is no pairing QR on v1.

OpenCode 2

API v2

Scan a QR, enter a pairing code, or use a host and password. Pairing needs OpenCode 2.0.25 or later.

1

Remote tunnel and QR

Away from the computer. API v2.

On the computer

opencode pair --remote

The first run asks before the server is exposed on the internet. Traffic is end-to-end encrypted, and access still uses your server password. The first start can take about a minute. The background service starts if it was stopped.

Then scan. In the app, tap Scan QR and point it at the code on the computer.

What the code does

  • The link and the code work once, and they expire in 5 minutes.
  • A saved tunnel stays until you turn remote access off.
  • Sessions last 30 days. Changing the server password signs every paired session out.
2

Same Wi-Fi and QR

Phone and computer on one network. API v2.

On the computer

The server has to be reachable past localhost before a QR appears.

opencode service set hostname 0.0.0.0
opencode pair

In the app, tap Scan QR.

3

Host, username, and password

API v1 and API v2. In the app, tap Use a host and password.

OpenCode 1, or a foreground server

The username defaults to opencode. Set OPENCODE_SERVER_USERNAME to change it. Keep the process running.

OPENCODE_SERVER_PASSWORD='choose-a-strong-password' \
  opencode serve --hostname 0.0.0.0 --port 4096

Default bind is 127.0.0.1. A phone cannot reach that. Use --hostname 0.0.0.0 for LAN or Tailscale.

OpenCode 2 background service

opencode service status prints the address. The default port is 49374 on macOS, Linux, and WSL, and 45278 on Windows. If opencode serve prints a password and you did not set one, use that password in the app.

opencode service set hostname 0.0.0.0
opencode service set password 'choose-a-strong-password'
opencode service start

In the app

  1. Enter the host. Use a LAN address, a .local name, a Tailscale name, or a tunnel host. Examples: 192.168.1.20:4096, macbook.local:49374.
  2. Username opencode, unless you changed it. Enter the password you set.
  3. Tap Connect. The app saves a Connection Profile and shows API v1 or API v2.

Leave the password empty only when the server has none. Set one before the server listens beyond that computer.

Check the foreground server

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

Healthy JSON with a version string means an API v1 server is up. That check is on the computer. The phone still needs the LAN, Tailscale, or tunnel address.

Off your network

Tailscale

Install Tailscale on the computer and the phone, same account. With the server on 0.0.0.0, use http://100.x.y.z:4096 or the MagicDNS name. A scanned QR prefers a Tailscale address when one answers.

Optional

Tailscale Serve

Keep the server on localhost and proxy it with tailscale serve 4096. Use the HTTPS URL Tailscale prints. Skip Funnel unless you want the public internet.

Simulator and emulator URLs
TargetBase URL
iOS Simulator on the same Machttp://127.0.0.1:4096
Android emulatorhttp://10.0.2.2:4096
Physical phoneLAN, Tailscale, or the remote tunnel

Use the port your server actually printed. OpenCode 2's background service is often 49374. The 4096 examples above are for opencode serve.

4

Pairing code

API v2, when the camera is unavailable

In the app

  1. Run opencode pair or opencode pair --remote on the computer.
  2. Tap Enter a pairing code. The code is the last part of the printed link, after /auth/connect/.
  3. Or paste the whole http://…/auth/connect/… link into the host field, then tap Connect.

The code works once and expires in 5 minutes. A typed code signs in as opencode.

✓

Checklist

One of these is enough

  • Server is running on the computer
  • Remote QR scanned, or same-Wi-Fi QR scanned
  • Or a host, username, and password saved
  • Phone uses a LAN, Tailscale, or tunnel address
  • App shows the server reachable, with API v1 or API v2
Troubleshooting
SymptomLikely cause
QR never prints Server still bound to localhost. Set hostname to 0.0.0.0, or run opencode pair --remote.
Scan fails Code expired after 5 minutes, or pairing changed. Use a host and password, or type a fresh pairing code.
Unreachable or timeout Server stopped, still on 127.0.0.1, wrong port, phone on another network, or Tailscale offline.
Authentication failed Wrong username or password. A new server password signs existing sessions out.
Works in the simulator, not on the phone The phone needs a LAN, Tailscale, or tunnel address.
Android emulator cannot reach the host Use http://10.0.2.2:4096, or the port the server printed.
Saved tunnel stops working Remote access was turned off. Run opencode pair --remote again and scan.

All docs · GitHub