Skip to content

Access OpenCode Remotely from Mobile

OpenCode Mobile can connect through a local address, private VPN, HTTPS tunnel, reverse proxy, SSH forward, or managed Cloud Link machine. The app needs an OpenCode API base URL; it does not require a specific tunnel provider.

Read the remote-access security model before publishing any endpoint.

Two separate decisions

Section titled “Two separate decisions”
  1. How will you reach the server? Choose a LAN, VPN, tunnel, proxy, SSH forward, or Cloud Link.
  2. How will you add the connection in the app? Use manual details, a local QR code, or Cloud Link.

The connection guide covers the in-app flow. This page compares the network routes.

Connection requirements

Section titled “Connection requirements”

Every manual route supplies the same three values:

  • Server URL: origin plus any required API path prefix
  • Username: OPENCODE_SERVER_USERNAME
  • Password: OPENCODE_SERVER_PASSWORD

Manual connections can also attach custom HTTP headers for a gateway, trust a private CA for that host:port, or sign in through OIDC. Local QR and Cloud Link profiles do not carry custom headers or a custom CA.

The client normalizes a missing protocol, preserves configured path prefixes such as /api, adds optional HTTP Basic authentication, and scopes session, file, terminal, and event requests to the selected project. The OpenCode 2 shared service uses the username opencode by default; its password is the one set with opencode service set password.

Start OpenCode for mobile

Section titled “Start OpenCode for mobile”
OpenCode version Recommended start App connection
OpenCode 2 shared service opencode service start, then opencode pair Scan the QR code or paste the pairing link
OpenCode 2 standalone opencode serve --hostname 127.0.0.1 --port 4096 Enter the URL and password manually
OpenCode 1.x opencode serve for the API, or opencode web for the browser UI Enter the URL and password manually

For OpenCode 2, set the service password before pairing:

Terminal window
opencode service set password 'use-a-strong-password'
opencode service set port 4096
opencode service start
opencode service status
opencode pair

The pair command prints a one-time link and QR code. Pairing links expire after five minutes and work once. When the hostname changes, restart the service before pairing again.

For a remote URL behind Tailscale, Cloudflare Tunnel, or a reverse proxy, create the pair link with that public origin:

Terminal window
opencode pair --url https://your-opencode-host.example

Pairing requires the shared background service. A standalone opencode serve process must be connected manually.

Choose a route

Section titled “Choose a route”
Method Use it when Guide
Local network Phone and server share a private Wi-Fi or LAN Local network
Local QR You want same-network setup without typing the address Add or switch connections
Tailscale Serve Only your own devices need access Tailscale
Cloudflare Tunnel You need a public HTTPS address without router port forwarding Cloudflare Tunnel
Reverse proxy or API prefix OpenCode is mounted under /api or another subpath Reverse proxy
SSH local forwarding A mobile SSH client can hold a port forward open SSH forwarding
Cloud Link You want managed remote access with a store subscription Cloud Link

For a decision-focused comparison, see Use OpenCode from your phone. For the in-app choices, see Add or switch connections.

Section titled “Local QR versus Cloud Link”

These are different features:

  • Local QR is a free, same-network setup shortcut on OpenCode 2. Start the shared service with opencode service start, run opencode pair, and scan the one-time code. The server must be reachable from the phone; a link containing only localhost will not work unless the phone owns that loopback route. Links expire after five minutes.
  • Cloud Link is an optional paid remote-access service for store-installed iOS and Android builds. It uses a desktop connector and a subscription to provide a managed route. It is not available in direct APK, F-Droid/FOSS, or web builds. See the OpenCode Cloud Link website for downloads, platform support, and pricing.

If you already have Tailscale or a reliable tunnel, you do not need Cloud Link.

Security guidance by method

Section titled “Security guidance by method”
Method Exposure Minimum guidance
LAN Private network Use auth, trusted Wi-Fi, and a private firewall rule
Tailscale Tailnet only Keep auth enabled and restrict tailnet membership/ACLs
Cloudflare Tunnel Public HTTPS URL Always use OpenCode auth; Cloudflare Access works with a manual connection’s custom headers
Reverse proxy Depends on proxy Use HTTPS, preserve streaming/WebSocket behavior, and require OpenCode auth
SSH forward Local loopback Protect the SSH key/account and keep the forwarding client alive
Cloud Link Managed tunnel Protect the store account and device; review the Cloud Link privacy details

On native iOS and Android builds, non-secret connection details use app storage. Server passwords, custom header values, CA material, and OIDC tokens use Keychain/Keystore-backed secure storage. Pending notification records contain the server URL and username but not the password. Browser builds cannot persist credentials through native secure storage.

Troubleshooting

Section titled “Troubleshooting”

Browser works but the app does not

Section titled “Browser works but the app does not”
  1. Test the exact API health URL, not only the browser UI.
  2. Upgrade to the latest OpenCode Mobile release.
  3. If the root serves HTML, enter the API base path, commonly /api.
  4. Confirm that a reverse proxy forwards SSE and terminal WebSockets as well as ordinary HTTP requests.

Authentication fails

Section titled “Authentication fails”
  • Match the username and password to OPENCODE_SERVER_USERNAME and OPENCODE_SERVER_PASSWORD.
  • If Password is set but Username is blank, the app defaults the Basic-auth username to opencode.
  • Reconnect after editing connection fields; editing alone intentionally does not start a new connection.

Connected but no project appears

Section titled “Connected but no project appears”

The server is reachable, but it may not expose a project catalog in the expected context. Refresh Projects, confirm the OpenCode version, and inspect Settings → Diagnostics for endpoint availability.

Local QR will not pair

Section titled “Local QR will not pair”
  • Confirm both devices are on a network that can reach each other.
  • Confirm the server is not listening only on localhost.
  • Run opencode pair again if the code expired or was already used.
Section titled “Cloud Link will not connect”

Confirm the app was installed from the App Store or Google Play, the subscription is active, the connector is running on the computer, and the QR code comes from the matching environment. See Cloud Link and Troubleshooting.

If the connection still fails, use the complete OpenCode Mobile troubleshooting checklist.