@kkcode-app/opencode-tunnel

A small CLI that starts opencode serve on your laptop and exposes it through an opencode-relay so the opencode-mobile app on your phone can connect — even if your laptop is behind NAT.

Install

cd cli
npm install

Usage

Default: spawn opencode serve for you

npx @kkcode-app/opencode-tunnel

This will:

1. Spawn opencode serve on 127.0.0.1:<random-port>.
2. Open a WebSocket tunnel to the relay.
3. Print a 6-character short code and QR code. In KKCode, open Servers → Scan tunnel QR code, then scan the terminal QR code.

Keep the terminal open while using the connection. The CLI reconnects after a temporary network loss. Use KKCode's manual server-address entry only for a normal LAN/Tailscale/OpenCode URL: a tunnel QR code contains a temporary access token and must be scanned.

Background service (macOS & Linux)

After pairing once in the foreground, install the tunnel as a background service so it auto-starts on login and auto-restarts on crash. On macOS it uses launchd (LaunchAgent), on Linux it uses a systemd user service.

npx @kkcode-app/opencode-tunnel --install

The first time you run --install it captures the current PATH and the absolute paths of node and opencode, so the background service can find them even though the service manager does not source your shell profile.

Other commands:

npx @kkcode-app/opencode-tunnel --status     # check if installed/loaded/running
npx @kkcode-app/opencode-tunnel --uninstall  # stop and remove the service

Logs are written to ~/.config/opencode-tunnel/tunnel.log. The host token is persisted across restarts, so your phone stays connected without re-scanning as long as the relay session hasn't expired.

Attach to an already running opencode serve

opencode serve --port 4096 &
npx @kkcode-app/opencode-tunnel --attach --port 4096

Flags

| Flag | Description | Default | | -------------------- | -------------------------------------------------------------- | ------------------------------------------------- | | --relay <url> | Relay base URL (ws:// or wss://) | $OPENCODE_RELAY_URL or wss://relay.kkcode.app | | --port <n> | Port for opencode serve (random free port if omitted) | random | | --hostname <h> | Local hostname for opencode serve | 127.0.0.1 | | --attach | Don't spawn — reuse an existing opencode serve | off | | --command <bin> | Binary to spawn | $OPENCODE_CMD or opencode | | --reset-host-token | Forget saved host token (forces a brand-new short code) | off | | --install | Install as macOS LaunchAgent (background, auto-start on login) | off | | --uninstall | Remove the LaunchAgent and stop the background service | off | | --status | Show whether the LaunchAgent is installed/loaded/running | off |

How it works

• The CLI registers as a "host" on the relay over a single WebSocket.
• The relay assigns a short code (e.g. DSHK3D) and a temporary client token.
• The phone hits https://relay.example.com/t/DSHK3D/... with the token in a header. The relay forwards each request frame-by-frame over the WebSocket to the CLI, which then fetch()es the local opencode serve and streams the response back.
• Streaming endpoints (SSE) pass through unchanged — chunks are forwarded as they arrive.

The host token is persisted in ~/.config/opencode-tunnel/config.json so that restarting or reconnecting the CLI gets you the same short code and client token while the relay session is valid, so the App stays connected without a second scan.

License

MIT.