OpenCode Mobile Bridge

OpenCode Mobile Bridge makes the OpenCode Web UI easier to use from a phone, tablet, or another browser on your local network.

It starts a private OpenCode server on your computer, exposes it through a LAN proxy, checks the available projects, and opens a seed page that loads your browser's OpenCode project list from OpenCode Desktop's saved projects.

Why This Exists

OpenCode Desktop can remember projects that do not always appear immediately in the OpenCode Web UI project picker. Mobile browsers also have their own local storage, so they often start with an empty project list.

This bridge solves that workflow by providing a /__seed page. The launcher opens that page automatically on the computer, and you can open the same seed URL from your phone. The page writes the known Desktop projects into that browser's OpenCode local storage, then redirects to OpenCode.

Features

• Installs OpenCode CLI with npm install -g opencode-ai@latest if it is missing.
• Installs Node.js automatically when possible if node is missing.
• Starts opencode serve on 127.0.0.1:4097 by default, so OpenCode does not open an empty raw Web UI tab before projects are seeded.
• Starts a LAN proxy on 0.0.0.0:4096 by default.
• Reuses an already-running OpenCode server or bridge proxy when possible.
• Removes OPENCODE_SERVER_PASSWORD and OPENCODE_SERVER_USERNAME for the launched server unless --keep-auth is used.
• Seeds browser project history from OpenCode's /project API.
• Also reads OpenCode Desktop's opencode.global.dat sidebar state to catch projects missing from the API.
• Supports manual project paths with --seed-project.
• Includes /__projects diagnostics to see exactly what the bridge found.
• Opens /__seed automatically after project discovery succeeds.

Requirements

• Python 3.10 or newer.
• Node.js available as node. If it is missing, the launcher tries to install Node.js LTS automatically on Windows with winget or on macOS with Homebrew.
• OpenCode CLI installed and available as opencode or at %APPDATA%\npm\opencode.cmd on Windows. If it is missing, the launcher tries to install it automatically with npm.
• Your phone and computer must be on the same local network.

Install Node.js and OpenCode manually if you do not want the launcher to install them:

winget install --id OpenJS.NodeJS.LTS -e

npm install -g opencode-ai@latest

Quick Start

From this folder:

python .\opencode-mobile-bridge.py

The script checks whether OpenCode is installed, starts whatever is missing, discovers projects, and opens the seed page automatically. It also prints URLs like:

LAN Web UI:     http://192.168.1.74:4096/
Seed projects:  http://192.168.1.74:4096/__seed
Debug projects: http://192.168.1.74:4096/__projects

On your phone or another device, open the printed Seed projects URL once:

1. Open the Seed projects URL.
2. Wait for it to redirect to OpenCode.
3. Use the LAN Web UI URL after that.

Common Commands

Use different ports:

python .\opencode-mobile-bridge.py --upstream-port 4097 --proxy-port 4096

Do not install Node.js automatically:

python .\opencode-mobile-bridge.py --no-install-node

Do not open a browser automatically:

python .\opencode-mobile-bridge.py --no-open

Open diagnostics instead of the seed page:

python .\opencode-mobile-bridge.py --open-target projects

Use opencode web instead of opencode serve:

python .\opencode-mobile-bridge.py --opencode-subcommand web

Add a project manually if it is not discovered:

python .\opencode-mobile-bridge.py --seed-project "C:\_Work\my-project"

Add multiple manual projects:

python .\opencode-mobile-bridge.py --seed-project "C:\_Work\project-a" --seed-project "C:\_Work\project-b"

Use a custom Desktop state file:

python .\opencode-mobile-bridge.py --desktop-global "C:\Users\MiPC\AppData\Roaming\ai.opencode.desktop\opencode.global.dat"

Keep OpenCode HTTP basic auth enabled:

python .\opencode-mobile-bridge.py --keep-auth

Project Seeding

The project list is merged in this order:

1. Manual paths from --seed-project.
2. OpenCode Desktop sidebar state from opencode.global.dat.
3. OpenCode server projects from /project.

Duplicates are removed. By default, only folders that exist on disk are included.

If you want to include paths even when they do not currently exist, set:

$env:OPENCODE_INCLUDE_MISSING_PROJECTS = "1"
python .\opencode-mobile-bridge.py

New Projects Not Showing

Each launcher run checks project discovery before opening the seed page. If you opened or created a new project in OpenCode Desktop and it does not appear on your phone:

1. Refresh or restart OpenCode Desktop so it writes its latest sidebar state.
2. Restart this bridge.
3. Open /__seed again from the browser/device that is missing the project. The seed page overwrites the browser's project list with the latest merged list.
4. Check /__projects to confirm whether the bridge found the folder.

If /__projects does not show it, launch with --seed-project "C:\path\to\project".

This area still needs improvement because OpenCode Desktop and OpenCode Web do not currently share one guaranteed project-history source. The bridge uses the best available sources and exposes diagnostics so missing paths are visible.

Password Prompts

OpenCode only asks for a username/password when OPENCODE_SERVER_PASSWORD is set.

By default this bridge removes these variables for the OpenCode process it launches. If you still see a browser password prompt:

1. Stop the bridge.
2. Close old OpenCode server terminals.
3. Run the bridge again with python .\opencode-mobile-bridge.py.
4. Make sure you are opening the printed LAN Web UI URL, not an older random Desktop sidecar URL.

If you intentionally use --keep-auth, the default username is usually opencode, and the password is whatever OPENCODE_SERVER_PASSWORD is set to.

Security Notes

This exposes OpenCode to your local network. Only use it on a network you trust.

For safer access:

• Keep the proxy bound to your LAN only.
• Stop the bridge when not using it.
• Use --keep-auth if you need password protection.
• Do not expose port 4096 to the public internet.

Troubleshooting

Check if the bridge is alive:

http://YOUR_PC_IP:4096/__health

Check discovered projects:

http://YOUR_PC_IP:4096/__projects

If your phone cannot connect:

• Confirm the phone is on the same Wi-Fi/LAN.
• Allow Python/Node/OpenCode through Windows Firewall when prompted.
• Try opening http://127.0.0.1:4096/ on the computer first.
• Verify no other process is already using port 4096.

Roadmap

• Better direct import from OpenCode Desktop project storage if the format changes.
• Optional automatic reseeding when Desktop project state changes.
• A packaged executable for Windows users.
• Optional authentication handling at the proxy layer.