Guide
From zero to your first session
A complete, copy-paste walkthrough: install opencode, start the server, connect the app over your LAN, and optionally enable the encrypted relay for access from anywhere — plus the full ocrelay command reference.
Install opencode
opencode mobile is a mobile client for opencode — start by installing the opencode CLI on the machine holding your projects. Already installed? Jump straight to the next step.
# official install script
$ curl -fsSL https://opencode.ai/install | bash
$ opencode --version
Start opencode serve
Start the server on the machine holding your projects. The app works with any opencode serve instance — if one is already running, you can skip this step.
# on the machine hosting your projects
$ export OPENCODE_SERVER_PASSWORD=your-secret
$ opencode serve --hostname 0.0.0.0 --port 4096
server listening on http://0.0.0.0:4096
Always set a password
OPENCODE_SERVER_PASSWORD turns on HTTP Basic auth for the server. Without it, anyone who can reach the address can drive your agent.
Bind to your LAN, not to the internet
The default bind only accepts local connections. Pass --hostname 0.0.0.0 (or your machine's LAN IP) so the phone can reach it — and keep the port off any public port-forwarding.
It is standard opencode
The server is the regular opencode CLI in headless mode. Models, providers and every other setting follow the official documentation.
Connect the app
Install opencode mobile on your phone and add the server as a connection profile. On the same Wi-Fi the app connects directly — no account, no relay, nothing in between.
- 01
Install the app
iOS via TestFlight, or the signed Android APK — both free.
- 02
Add a connection profile
Enter the server address (for example http://192.168.1.10:4096), the username and the password you set on the server.
- 03
Pick a project and start a session
Choose the directory the agent should work in. Everything it does streams back to your phone in real time.
Your platform
Get the app- iPhone running iOS 17 or later
- An opencode serve instance reachable from your phone
Enable the relay
Not on the same network? opencode relay tunnels your server through Cloudflare's edge so the phone can reach it from anywhere — no public IP, no port forwarding. You set it up once, on the machine running opencode serve.
- 01
Sign in to the relay in the app
Sign in with an email code; a free account is created on first sign-in and includes 512 MB of traffic per month.
- 02
Install ocrelay
Run the official install script on the machine that hosts opencode serve.
- 03
Run connect, then pair once
ocrelay connect asks for the opencode address, username and password, then shows a QR code. Scan it in the app — pairing codes are single-use and expire.
- 04
Done
The app can now reach your server from any network. On your LAN it still connects directly; the relay only carries traffic when it has to.
# install the relay client
$ curl -fsSL https://opencodemobile.com/install.sh | bash
# start pairing; runs in the foreground
$ ocrelay connect
local opencode address [http://localhost:4096]: http://localhost:4096
username [admin]: admin
password: ••••••••••
pairing code: 7QK4-2X9C
scan the QR code with the app to finish pairing
paired — press b to run in the background
Your opencode password stays on that machine: the relay client injects it locally, and the relay only ever sees encrypted traffic.
ocrelay command reference
Four subcommands cover everything the relay client does. Credentials and pairing state persist locally after the first successful run.
| Command | What it does |
|---|---|
| ocrelay connect | Pair and wait for the app to open a session. Runs in the foreground; once online, press b to move it to the background. |
| ocrelay stop | Stop an ocrelay instance running in the background. |
| ocrelay status | Show pairing and local status — a purely local check. |
| ocrelay upgrade | Check for and install the latest release. |
| ocrelay connect --re-pair | Force a fresh QR pairing. Your local opencode settings are kept; unpair the old device in the app first. |
| ocrelay --version | Print the client and protocol version. |
Need to change the opencode address, username or password? Run ocrelay connect again and choose to set them up once more.
Stuck on something?
The FAQ covers connectivity, pairing and billing questions. If your answer is not there, the feedback inbox reaches the team directly.