Connecting

Ways to reach the OpenCode running on your computer from your phone. At home, use the same Wi-Fi. To also connect when you are out, Tailscale is the easiest choice.

First, start the server

Whichever way you connect, start OpenCode on your computer with a password.

export OPENCODE_SERVER_PASSWORD=your-password
opencode serve --hostname 0.0.0.0 --port 4096

In Windows PowerShell, set it with $env:OPENCODE_SERVER_PASSWORD="your-password" before starting. Enter the same password on the app's connect screen (leave the username as opencode).

Without a password, anyone on the same network can control your computer. Always set one.

If OpenCode runs on the computer too

OpenCode is client–server: one server owns sessions, permissions and questions (forms), and the desktop app or the opencode TUI is just a client that connects to it. If you use one of those on the computer and also start a separate opencode serve, you end up with two servers. Questions and permissions raised on the computer then never appear on your phone (and the other way around). Message history is shared, so it looks like it works, which makes this easy to miss.

In that case, don't run opencode serve. Expose the shared server (background service) the computer already uses instead:

opencode service set hostname 0.0.0.0
opencode service restart
opencode service status   # shows http://0.0.0.0:4096 when it worked

Pinning the port to 4096 keeps the app's automatic discovery and http://192.168.1.10:4096 working:

opencode service set port 4096
opencode service restart

A password is set for you. Read it with opencode service get password and enter it in the app (this is different from the password you choose for opencode serve).

The opencode serve step above is for using that server alone (no desktop app or TUI on the computer). Either way, check the state with opencode service status and restart it with opencode service restart.

Connect with a QR code (no password to type)

If you use the shared server (background service) above, run this on your computer to show a QR code and a link for connecting.

opencode pair

On the app's connect screen, tap Scan QR code to connect and scan that code. You can also send the link to your phone and paste it into the server URL field. Either way, there's no password to type.

The QR code and link expire after 5 minutes and work only once. If they expire, run opencode pair again. The key the app receives lasts 30 days and stops working if you change the server password; just scan again when that happens.

Your phone still has to reach your computer's address, as with any other method, so use it together with the same Wi-Fi or Tailscale options below.

On the same Wi-Fi

The simplest way, when your phone and computer share a Wi-Fi network.

  1. Start the server as above.
  2. Open the app's connect screen. Servers on the same network show up on their own; tap one and enter the password.
  3. If yours doesn't appear, look up the computer's IP address and enter it like http://192.168.1.10:4096.
    Mac: ipconfig getifaddr en0 Windows: ipconfig Linux: hostname -I

If it still can't connect, check that the computer's firewall allows connections on port 4096. This way does not work when you are away from home.

With Tailscale (works from anywhere)

Tailscale joins your own devices in a private, encrypted network. It is free for personal use, and nothing is opened to the internet.

  1. Install Tailscale on both your computer and your phone, and sign in with the same account.
  2. Start the server as above.
  3. On the computer, run tailscale ip -4 and note the address starting with 100..
  4. In the app, enter it like http://100.x.y.z:4096 and connect. With MagicDNS on, http://computer-name:4096 works too.

While the Tailscale app on your phone is on, this works over mobile data as well.

For HTTPS, start OpenCode with --hostname 127.0.0.1 and run tailscale serve --bg 4096 on the computer; then connect to https://computer-name.your-tailnet.ts.net.

With Cloudflare Tunnel

For when you can't install Tailscale. Your computer opens a tunnel to Cloudflare, which gives it a public HTTPS address.

  1. Install cloudflared on the computer.
  2. Start the server as above (--hostname 127.0.0.1 is fine here).
  3. In another terminal, run:
    cloudflared tunnel --url http://localhost:4096
  4. Enter the https://….trycloudflare.com address it prints in the app and connect.

Anyone who learns the address can reach your server, so use a long, hard-to-guess password. The address changes every time you start the tunnel; for a fixed one, create a named tunnel in your Cloudflare account.

With SSH port forwarding

For people who already SSH into their computer. Set up forwarding in an SSH app on your phone (Termius, for example).

  1. Start OpenCode on the computer with --hostname 127.0.0.1.
  2. In the SSH app, add a local port forward from port 4096 on the phone to 127.0.0.1:4096 on the computer.
  3. With the forward running, connect the app to http://127.0.0.1:4096.

The forward may stop when the SSH app goes to the background, especially on iPhone. For everyday use, Tailscale is steadier.

If something doesn't work

"Connection check" in the ⋮ menu at the top right of the project list shows at a glance whether the server answers, live updates flow, and the notification plugin and MCP servers are working. You can copy the results into a support request.