@ccpocket/bridge

Bridge server that connects Claude sessions powered by the Claude Agent SDK and Codex CLI to mobile devices via WebSocket.

This is the server component of ccpocket — a mobile client for Claude and Codex.

Quick Start

npx @ccpocket/bridge@latest

A QR code will appear in your terminal. Scan it with the ccpocket mobile app to connect.

Claude sessions use ANTHROPIC_API_KEY by default. Subscription authentication through the Bridge machine's Claude Code login is available only after explicit opt-in with BRIDGE_ALLOW_CLAUDE_OAUTH=1; see Claude Subscription Authentication. Hosts that run Claude Code on Amazon Bedrock need neither of those; see Claude on Amazon Bedrock.

Installation

# Recommended: run the latest Bridge directly
npx @ccpocket/bridge@latest

# Optional: install globally
npm install -g @ccpocket/bridge
ccpocket-bridge

# Show CLI help or version
ccpocket-bridge --help
ccpocket-bridge --version

Configuration

Lowercase proxy variables (https_proxy, http_proxy, all_proxy) are also supported. When BRIDGE_PROMPT_HISTORY_FILE is not set and BRIDGE_PORT is not 8765, prompt history is stored in $HOME/.ccpocket/prompt-history-v2-<port>.json.

Push relay uses Firebase Anonymous Auth automatically; no FCM environment variables are required.

Claude Subscription Authentication (Explicit Opt-In)

Anthropic's Legal and compliance page says its Commercial Terms do not prevent a platform from hosting the unmodified Claude Code binary when each end user signs in with their own subscription or other credentials, subject to the conditions listed there. CC Pocket similarly runs Anthropic's official Agent SDK on the user's Bridge machine and delegates credential loading to the host's Claude Code environment. CC Pocket does not copy, store, or refresh Claude OAuth credentials itself.

Running Claude Code on a user's computer and controlling it remotely is also a common pattern among tools such as OpenClaw, Happy, and Termopus, although their exact implementations differ from CC Pocket.

However, Anthropic's Agent SDK overview also says that, unless previously approved, third-party products should use API keys rather than offer Claude.ai login or subscription rate limits. The scope of these two statements is not clear for CC Pocket's architecture, so subscription authentication may be restricted or stop working in the future.

To avoid that uncertainty, use ANTHROPIC_API_KEY. If you understand the risk and want to use the Bridge machine's Claude Code subscription login, enable it explicitly and restart Bridge:

BRIDGE_ALLOW_CLAUDE_OAUTH=1 npx @ccpocket/bridge@latest

Only the exact value 1 enables this behavior. Service setup preserves the setting when it is present in the setup environment.

# Example: custom port with API key
BRIDGE_PORT=9000 BRIDGE_API_KEY=my-secret npx @ccpocket/bridge@latest

# Example: allow projects outside $HOME
BRIDGE_ALLOWED_DIRS="$HOME,/scratch/$USER" npx @ccpocket/bridge@latest

# Example: expose Bridge through a reverse proxy / ngrok
BRIDGE_PUBLIC_WS_URL=wss://example.ngrok-free.app npx @ccpocket/bridge@latest

# Example: same setting via CLI flag
ccpocket-bridge --public-ws-url wss://example.ngrok-free.app

# Example: disable mDNS advertisement
BRIDGE_DISABLE_MDNS=1 npx @ccpocket/bridge@latest
# or via CLI flag
ccpocket-bridge --no-mdns

# Example: use an assist model provided by a custom Codex gateway
BRIDGE_CODEX_ASSIST_MODEL=gpt-oss:20b-cloud \
BRIDGE_CODEX_ASSIST_REASONING_EFFORT=none \
npx @ccpocket/bridge@latest

When BRIDGE_PUBLIC_WS_URL is set, the startup deep link and terminal QR code use that public URL instead of the LAN address. This is useful when the Bridge is reachable through a reverse proxy, tunnel, or public domain.

Without it, the printed QR code is LAN-oriented by default and typically encodes something like ws://192.168.x.x:8765.

Claude on Amazon Bedrock

Claude Code and the Claude Agent SDK can run against Amazon Bedrock instead of the first-party Anthropic API. Bedrock requests are signed with AWS credentials, so the Bridge requires neither ANTHROPIC_API_KEY nor the subscription opt-in:

CLAUDE_CODE_USE_BEDROCK=1 \
AWS_REGION=us-west-2 \
npx @ccpocket/bridge@latest

# AWS_PROFILE optionally selects a specific credential profile. AWS_REGION is
# still required because Claude Code does not read it from the AWS profile:
CLAUDE_CODE_USE_BEDROCK=1 AWS_REGION=us-west-2 AWS_PROFILE=my-profile \
  npx @ccpocket/bridge@latest

AWS credentials remain on the Bridge host and are resolved through the normal AWS credential provider chain — environment credentials, AWS_PROFILE, ~/.aws/credentials, ~/.aws/config, IAM roles, SSO, and EC2/ECS credentials. CC Pocket has no AWS credential store of its own. The Bridge parses the Claude settings file to detect the Bedrock flag and region, but does not access or persist credential fields, log credential values, or send AWS configuration to the mobile app. Claude Code resolves credentials on the Bridge host.

The Bridge also recognizes Bedrock when Claude Code's /setup-bedrock wizard wrote CLAUDE_CODE_USE_BEDROCK into the env block of the Claude Code user settings file (~/.claude/settings.json, or $CLAUDE_CONFIG_DIR/settings.json). Only the Bedrock flag and AWS_REGION are accessed from the parsed settings.

Bedrock normally authenticates without Claude OAuth. If Claude Code reports an OAuth authentication source despite the Bedrock flag, the Bridge still requires BRIDGE_ALLOW_CLAUDE_OAUTH=1 and rejects the session without that explicit opt-in.

Model IDs, region resolution, and IAM permissions follow the Claude Code documentation. CC Pocket adds no Bedrock-specific configuration of its own.

Verify the result with the doctor command:

npx @ccpocket/bridge@latest doctor

The Claude Code CLI line then reads Amazon Bedrock configured; AWS credentials not verified. Doctor reports the configuration only — it does not call AWS, so it never claims that credentials work. If AWS_REGION is missing, doctor warns instead of reporting Bedrock as configured.

Amazon Bedrock with the background service

ccpocket-bridge setup persists only the BRIDGE_* settings listed below, so make the Bedrock configuration reachable from the service environment:

• macOS launchd: the generated plist starts the Bridge through a login shell (zsh -li), so export CLAUDE_CODE_USE_BEDROCK=1 and any AWS_* variables in ~/.zprofile / ~/.zshrc are inherited.
• Linux systemd: the generated unit starts the Bridge through a login shell (bash -lc), so exports in ~/.profile / ~/.bash_profile are inherited. Environment= lines added to ~/.config/systemd/user/ccpocket-bridge.service also work, but re-running setup rewrites that file.
• Either platform: keeping the configuration in the Claude Code user settings env block works too, and survives re-running setup.

Persistent service setup

Register the Bridge as a user-level background service:

npx @ccpocket/bridge@1 setup

Setup supports macOS launchd and Linux systemd. It persists the Bridge settings that affect startup:

• BRIDGE_PORT / --port
• BRIDGE_HOST / --host
• BRIDGE_API_KEY / --api-key
• BRIDGE_INSECURE_NO_AUTH / --insecure-no-auth
• BRIDGE_ALLOWED_DIRS
• BRIDGE_FILE_DOWNLOAD_ALLOW_ALL_PATHS
• BRIDGE_PUBLIC_WS_URL / --public-ws-url
• BRIDGE_DISABLE_MDNS / --no-mdns
• BRIDGE_ALLOW_CLAUDE_OAUTH
• BRIDGE_CODEX_APP_SERVER_MODE / --codex-app-server-mode
• BRIDGE_CODEX_SHARED_APP_SERVER_URL / --codex-shared-app-server-url
• BRIDGE_CODEX_ASSIST_MODEL
• BRIDGE_CODEX_ASSIST_REASONING_EFFORT

Example:

BRIDGE_ALLOWED_DIRS="$HOME,/scratch/$USER" \
BRIDGE_API_KEY=my-secret \
npx @ccpocket/bridge@1 setup

To persist the explicit subscription-authentication opt-in:

BRIDGE_ALLOW_CLAUDE_OAUTH=1 npx @ccpocket/bridge@1 setup

Custom gateway users can persist assist overrides in the same way:

BRIDGE_CODEX_ASSIST_MODEL=gpt-oss:20b-cloud \
BRIDGE_CODEX_ASSIST_REASONING_EFFORT=none \
npx @ccpocket/bridge@1 setup

Showing the pairing QR code again

A background service writes its startup output to a log file. To pair another device, print the QR code of the Bridge running on this machine:

npx @ccpocket/bridge@1 qr            # default port 8765
npx @ccpocket/bridge@1 qr --port 9000

The QR code includes the API key, so only show it to devices you trust. Run the command as the same OS user as the Bridge: it reads the local-only /pairing endpoint with a per-start secret stored in ~/.ccpocket/pairing-secret-<port> (mode 0600). The endpoint also rejects non-loopback requests and browser requests (Origin header), so other machines, other local users and web pages cannot read the key.

Security

The Bridge always requires an API key unless you pass --insecure-no-auth. If you do not set BRIDGE_API_KEY, the first start generates a key and stores it in ~/.ccpocket/bridge-api-key; later starts reuse it. Pair devices with the QR code shown when the Bridge starts in a terminal, or with npx @ccpocket/bridge@1 qr for a background service. Desktop apps take the API key printed by the same command. To rotate the key, delete the file and restart the Bridge, then pair your devices again.

/usage, /doctor, gallery upload and gallery delete require Authorization: Bearer <key>. /health and /version stay public.

Plain ws:// is not encrypted, so on untrusted networks such as café Wi-Fi prefer Tailscale or wss://.

On Linux, setup gives standalone Codex installs priority by including $HOME/.local/bin before npm-managed Node paths in the service PATH.

Experimental: Join a CC Pocket Codex Session from Codex CLI

By default, each Codex session uses a private app-server. To let Codex CLI join the same live thread that CC Pocket started, run the Bridge with shared app-server mode:

BRIDGE_CODEX_APP_SERVER_MODE=managed \
BRIDGE_CODEX_SHARED_APP_SERVER_URL=ws://127.0.0.1:8767 \
npx @ccpocket/bridge@latest

Then start or resume a Codex session from CC Pocket. When the session is ready, the session screen can copy a session-specific command like:

codex resume <thread-id> --remote ws://127.0.0.1:8767

Run that command in a terminal on the same machine as the Bridge. The 127.0.0.1 address is for the Mac/Linux machine running the Bridge and Codex CLI, not for the phone.

Modes:

• private: default behavior. No Codex CLI co-presence.
• managed: Bridge starts one local WebSocket Codex app-server and shares it with Codex CLI.
• external: Bridge connects to an already-running app-server. In this mode, BRIDGE_CODEX_SHARED_APP_SERVER_URL is required.

This is experimental and currently targets Codex CLI co-presence only. Codex App compatibility is not guaranteed and may use a different integration model in the future.

Requirements

• Node.js v22.19.0+
• Claude Code CLI and/or Codex CLI

Current Codex CLI docs recommend the standalone installer for macOS/Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Health Check

Run the built-in doctor command to verify your environment:

npx @ccpocket/bridge@latest doctor

It checks Node.js, Git, CLI providers, macOS permissions (Screen Recording, Keychain), macOS sleep settings, network connectivity, and more.

Architecture

Mobile App ←WebSocket→ Bridge Server ←stdio→ Claude Code CLI

The bridge server spawns and manages Claude Code CLI processes, translating WebSocket messages to/from the CLI's stdio interface. It supports multiple concurrent sessions.

License

This package is MIT licensed as part of CC Pocket. See LICENSE and the repository root LICENSE.

Sharing files by absolute path

Sharing accepts both project-relative and absolute file paths. By default, the resolved file (including symlink targets) must stay inside the selected project and BRIDGE_ALLOWED_DIRS.

To explicitly allow sharing files from any location:

BRIDGE_FILE_DOWNLOAD_ALLOW_ALL_PATHS=1 npx @ccpocket/bridge@latest

This opt-in grants connected clients download access to all regular files readable by the Bridge process. The selected project must still be an allowed, existing directory. Authentication, download size limits, and capability URLs remain in place. Uploads and other file access operations retain their existing rules. Set the variable when running setup to persist it in launchd/systemd, or update the service environment and restart the Bridge. No mobile app update is needed.