Set Up OpenCode Mobile

This guide covers the shortest safe path from an OpenCode server to your first completed mobile task. OpenCode 2 is the current primary target; the app also supports OpenCode 1.x servers with manual connections for the core surface.

What you need

An Android device (64-bit ARM) or iPhone/iPad.
A computer or server running a current OpenCode version.
A network route from the phone to the server: local network, VPN, tunnel, reverse proxy, SSH forward, or Cloud Link.
The server URL and password, or a one-time pairing link/QR code.

1. Install OpenCode Mobile

Use the Download page to choose an installation method:

Google Play (recommended): install and receive updates through Google Play.
Direct GitHub APK: download and install the latest release manually. Android release artifacts are arm64-v8a only.
iOS TestFlight beta: join the OpenCode Mobile TestFlight release and install the beta.

The Android options install the latest Android release; TestFlight installs the iOS beta. See Download and install for platform-specific details.

2. Install or update OpenCode

For OpenCode 2, use the current v2 installer:

curl -fsSL https://opencode.ai/v2/install | bash

Or install the CLI with npm:

npm install -g @opencode/cli

Confirm the installed major version:

opencode --version

If you deliberately use an OpenCode 1.x server, install it with the 1.x installer (https://opencode.ai/install or opencode-ai on npm) and use the V1 startup note below.

3. Start OpenCode

Recommended: OpenCode 2 shared service and pairing

OpenCode 2 normally runs a shared background server. Start it explicitly, confirm its address, and create a pairing link:

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

opencode pair prints a one-time link and a QR code. Scan the QR code from OpenCode Mobile, or paste the pairing link into the app. Pairing links expire after five minutes and work once.

If the phone is on the same trusted LAN, bind the service to a reachable interface before pairing:

opencode service set hostname 0.0.0.0
opencode service start
opencode pair

Only do this on a trusted network and protect the server with a password. For access through Tailscale, Cloudflare Tunnel, or a reverse proxy, keep the service on loopback and pair with the public URL. If you changed the hostname for LAN access, set it back and restart before pairing:

opencode service set hostname 127.0.0.1
opencode service start
opencode pair --url https://your-opencode-host.example

OpenCode 2 also supports opencode pair --remote, which exposes the server through an OpenTunnel address after an explicit confirmation. This is separate from Cloud Link. Treat the tunnel like any other public endpoint and review the remote-access security guidance.

Standalone server

opencode serve runs the same server in the foreground instead of through the shared background service:

OPENCODE_SERVER_PASSWORD='use-a-strong-password' \
  opencode serve --hostname 127.0.0.1 --port 4096

Use this for an always-on host, a service supervisor, Docker, or a deliberately dedicated server. Pairing requires the shared service, so connect to a standalone server manually with its URL and password.

OpenCode 1.x

On OpenCode 1.x, start opencode serve for the API, or opencode web when you also want the browser UI:

export OPENCODE_SERVER_USERNAME=your-user
export OPENCODE_SERVER_PASSWORD='use-a-strong-password'
opencode serve --hostname 127.0.0.1 --port 4096

Connect V1 servers manually. Local QR pairing is an OpenCode 2 feature. V1 is maintained for the feature intersection with V2; archive/share, title summarization, worktree reset, LSP/formatter diagnostics, and the composer auto-approve/saved-rules surfaces are not available.

Verify the server

With the shared service running:

opencode api get /api/info

For a manual or external connection, test the exact API base from the phone’s network:

curl -u your-user:use-a-strong-password \
  https://your-opencode-host.example/global/health

For a path-prefixed proxy, include the prefix:

curl -u your-user:use-a-strong-password \
  https://your-opencode-host.example/api/global/health

A healthy response includes healthy: true and may include the OpenCode version. If the root displays a web UI and the app reports a 404 or a non-API response, enter the API base URL instead—commonly the same address with /api.

4. Choose a connection route

Route	Best for	Phone-side action
Local network	Phone and server on the same private network	Scan `opencode pair`, or enter the LAN URL
Tailscale	Private access across networks	Scan a pair link created with `--url`, or enter the `ts.net` URL
Cloudflare Tunnel	Public HTTPS without router port forwarding	Scan a pair link created with `--url`, or enter the tunnel URL
Reverse proxy	Existing HTTPS infrastructure or a path prefix	Scan a pair link created with `--url`, or enter the API base
SSH local forward	Advanced users with a mobile SSH client	Enter `http://127.0.0.1:4096` manually
Cloud Link	Managed access with a store subscription	Scan the connector QR

Follow Remote Access for the exact commands and security tradeoffs. Use the dedicated Tailscale, Cloudflare Tunnel, local network, or Cloud Link guide for the route you choose.

Cloud Link is a separate connector product. See the OpenCode Cloud Link website for connector downloads, platform support, and pricing.

5. Connect the app

On first launch, onboarding walks through these steps:

Welcome — continue into setup.
Permissions — optionally enable notifications and voice input.
Connect — add a server connection.
AI & providers — optionally configure providers, models, and automatic routing.
Project — choose a server project or add a folder.
General — choose the interface language and, on V2, prompt delivery.
Voice & responses — choose how you talk and hear replies.
Privacy — choose local diagnostics and, when available, optional remote telemetry.
Ready — review the setup and start.

The AI and Project steps appear after a connection exists, so a first run that skips the server sees fewer steps. Every step has a Skip action.

In Connect, the Add connection chooser offers:

Scan QR code — scan the link printed by opencode pair. The link must contain an address the phone can reach; a loopback-only link will not work across devices unless the phone itself owns that loopback route.
Manual — enter a name (optional), the complete server URL, username, and password. Manual connections can also add custom HTTP headers, a custom CA certificate, or OpenID Connect.
Cloud Link — pair with a managed connector when the app was installed from the App Store or Google Play and an active subscription is available.

For manual setup, include https:// and any required path prefix. If a password is set and Username is blank, the client uses opencode as the Basic-auth username. Entering the explicit server username is clearer and easier to troubleshoot.

You can skip permissions, connection, or project during onboarding and configure them later in Settings → Connection and the Projects tab. Editing a saved connection does not reconnect automatically; use Reconnect when you want to apply the change.

See Add or switch connections for saved profiles, pairing details, custom headers, certificates, OIDC, Cloud Link, and switching servers.

6. Select a project

Choose the project during onboarding or later in Projects. The picker lists the projects the server reports, in server order. Search filters the list; Add project opens a server folder browser with a manual path fallback.

The selected project scopes chats, files, and terminal activity. The app remembers the last session used for each project. If a project does not appear, confirm the server reported it or add the server directory from the project picker.

To hide a server project on this device only, use its archive action. On OpenCode 2, Archived on OpenCode shows server-archived projects as read-only with a location-based restore. See Projects.

7. Complete your first task

Open Chat and confirm the expected session title and project appear at the top.
Select the agent and model above the composer.
Send a small, verifiable request such as: Inspect this project and summarize its purpose. Do not change files.
Watch the transcript while OpenCode works.
Respond if a permission or question card appears.
Tap the change chip above the composer and confirm that the read-only task produced no edits.

For your first implementation task, ask for one contained change and its related test. Review both the assistant response and the changes overlay before accepting the result.

8. Check optional capabilities

After connecting, use Settings → Diagnostics and the Projects tab to confirm which features the server exposes:

Provider and model discovery, variants, and automatic model routing
Global realtime events
MCP, health, network, and app-error diagnostics
Extension management on OpenCode 2
File status and VCS information
Device-local project archive and, on V2, server-archived projects
Experimental worktrees
PTY terminal support
V2 media preview, downloads, and file copy/move/rename/delete
V2 saved approval rules and composer auto-approve
V2 plugin GUI panels

Missing optional endpoints should not prevent core chat use. See Releases and compatibility for the current contract differences.

Security notes

Never expose an unauthenticated OpenCode server to the public internet.
Prefer Tailscale, Cloudflare Tunnel, or an authenticated HTTPS reverse proxy over router port forwarding.
Use 0.0.0.0 only for a trusted LAN and restrict the port with the host firewall.
Set a strong OpenCode service password. Pairing links are credentials: they expire quickly and work once, but they still grant access while valid.
On native iOS and Android builds, connection passwords, custom header values, CA material, and OIDC tokens use secure storage; non-secret connection details use app storage.
Treat the device as containing access to your OpenCode server. Rotate credentials if a tunnel URL, device, or password is compromised.
Cloud Link is optional. Review the privacy policy before subscribing.

If connection still fails

Confirm the phone can reach the exact API URL.
Run opencode service status and opencode api get /api/info on the server.
Confirm the phone is connected to the same Tailscale tailnet when using Tailscale.
Check the password against opencode service set password or the OPENCODE_SERVER_PASSWORD environment variable.
For local pairing, run opencode pair again if the link expired or was already used.
For a standalone opencode serve process, connect manually; pairing requires the shared service.
If the address returns HTML, 404, or a JSON parse error, use the actual API base path.
If a gateway returns 401 or 403, check the connection’s custom headers.
If a certificate is rejected, confirm it covers the same host:port and has not expired.
If OIDC expires, confirm the issuer and redirect URI, then sign in again.
Update to the latest mobile release and check Settings → Diagnostics.
Continue with the connection troubleshooting checklist before filing a bug.