@claude-mobile/bridge

Bridge server for Claude Code Mobile — wraps the Claude Agent SDK and exposes it over WebSocket so the mobile/PWA app can drive Claude Code from your phone.

Quickstart

npx @claude-mobile/bridge

That's the whole setup. The bridge starts a secure tunnel, then opens a connect page in your browser:

✦ Claude Code Bridge — my-laptop
  Reachable from anywhere
  Opening http://localhost:3578/connect …

Point your phone's camera at the QR code on that page. Your phone's normal camera app opens the mobile app and connects it — there is nothing to type. To use the app on the same computer instead, click Connect this computer.

The first time a device connects, the page asks you to approve it:

iPhone · Safari wants to connect     [Approve]  [Deny]

After that, the device reconnects silently.

On first run you'll be prompted for an ANTHROPIC_API_KEY (get one here). It's stored at ~/.config/claude-code-bridge/config.env (mode 0600). Without one, the bridge falls back to your local claude CLI login, so a Pro/Max subscription works with no key at all.

How devices are trusted

Rather than sharing one password, each device is paired individually:

| Credential | Lifetime | Purpose | | ------------ | --------------------- | ---------------------------------------------- | | Pairing code | 5 minutes, single use | Proves the device saw your QR code | | Device token | Until revoked | Issued on approval; used for later connections |

Nothing is displayed for you to type or copy, so there is nothing to leak in a screenshot or a screen share. A QR captured from a shared screen stops working within five minutes, and a device can only get in if you approve it on your own machine.

Paired devices are listed on the connect page and can be revoked individually.

Options

| Flag | Effect | | ------------------ | ------------------------------------------------------------------------------ | | --no-tunnel | Local network only. Implies --lan. | | --lan | Also listen on the local network while the tunnel is running. | | --qr | Also print a QR code in the terminal (useful over SSH). | | --no-open | Don't open a browser; print the connect URL instead. | | --trust-lan | Auto-approve local-network devices. Tunnel connections still require approval. | | --trust-all | Disable approval entirely. Unsafe with the tunnel enabled. | | --forget-devices | Unpair every device and exit. | | --setup-api-key | Store an Anthropic API key and exit. |

Environment

Read in this order, later entries winning:

1. ~/.config/claude-code-bridge/config.env (%APPDATA%\claude-code-bridge\config.env on Windows)
2. .env in the current directory
3. Process environment

| Variable | Default | Notes | | -------------------------- | -------------- | ------------------------------------------------- | | ANTHROPIC_API_KEY | — | Falls back to your local claude CLI login | | PORT | 3578 | TCP port | | AUTH_TOKEN | random | Legacy shared token for automation; skips pairing | | PWA_URL | the hosted app | Point the QR at your own deployment | | CLAUDE_BRIDGE_CONFIG_DIR | OS default | Where config, devices and titles are stored |

Networking

By default the bridge listens only on 127.0.0.1, with the tunnel reaching it locally, so it is not exposed to your local network. Pass --lan if you use the native app over Wi-Fi and want the faster direct route.

The tunnel uses Cloudflare Quick Tunnels; the cloudflared binary downloads automatically on first use (~30 MB). If it cannot be installed, the bridge falls back to local-network-only and says so.

Quick Tunnel URLs change on every restart, so a saved connection goes stale when you restart the bridge — scan the QR again. Leave the bridge running and this rarely comes up.

Auto-start on macOS

From a checkout of the source repo:

npm run setup -w @claude-mobile/bridge     # installs a launchd plist
npm run unsetup -w @claude-mobile/bridge   # removes it

Approval happens on the connect page rather than in the terminal, so this works headless — open http://localhost:3578/connect whenever a new device needs approving.

License

MIT