Claude Code Bridge

Claude Code Bridge

Connect to Claude Code through PandaNpc — two connection modes for different scenarios.

Connection Modes

Mode Scenario Port Required
Relay (recommended) Claude runs on another machine, connect via relay No
Local Claude runs on this machine No

Best for: Your Claude runs on a home PC / server, and you want to access it from anywhere — phone, laptop, office — without opening any ports.

Your PC (cc-bridge)  ──outbound WSS──▶  Relay Server  ◀──outbound WSS──  PandaNpcApp
                                       cc.pandanpc.com
Both sides connect OUT. Zero ports opened. Works behind any firewall/NAT.

Step 1: Install cc-bridge on your server

macOS / Linux:

curl -fsSL https://pandanpc.com/cc-bridge/install.sh | sh

Windows (PowerShell):

iwr https://pandanpc.com/cc-bridge/install.ps1 -UseB | iex

After installation you'll see:

=== cc-bridge installed (relay mode) ===

  Bridge ID: bridge-a1b2c3d4
  Token:     77a1449c3119aa87e16b95b13c40d03f...

  Open PandaNpcApp -> New Connection -> Relay mode

Copy the Bridge ID and Token.

Step 2: Connect from PandaNpcApp

  1. Open PandaNpc → Claude Code page
  2. Click New Connection
  3. Select Relay mode
  4. Fill in:
    • Bridge ID: the ID shown after install (e.g. bridge-a1b2c3d4)
    • Token: the token shown after install
    • Working Directory: the remote directory for Claude to work in
  5. Click Create & Connect

Session Resume

If you refresh the page or lose connection:

  • Within 5 minutes: Reconnects to the same Claude process — context fully preserved, last 50 messages replayed
  • After 5 minutes: Starts a new Claude with --resume — loads conversation history from disk

No manual action needed. PandaNpcApp automatically attempts resume on reconnect.

Local Mode

Best for: Running Claude directly on the machine where PandaNpcApp is installed. Simplest setup, zero network.

Prerequisites

Install Claude Code CLI:

claude --version

Usage

  1. Open PandaNpc → Claude Code page
  2. Click New Connection
  3. Select Local mode
  4. Working Directory: click "Browse" to select a folder
  5. Click Create & Connect

PandaNpc spawns Claude as a local subprocess. No network, no ports, no bridge needed.

Security

Relay mode

Layer Purpose
Bearer Token Only those with the token can connect to your bridge
TLS (WSS) All traffic encrypted between bridge ↔ relay ↔ app
Session isolation Each bridge has a unique ID, sessions cannot cross bridges

Who can't connect?

Scenario Result
No token ❌ Rejected
Wrong Bridge ID ❌ Bridge not found
Wrong token ❌ Unauthorized
PandaNpcApp + correct Bridge ID + Token ✅ Connected

Token Management

  • Lost? Re-run the install script — it reuses existing token from .env
  • Compromised? Stop service → delete .env → re-run install script
  • Rotation? Recommended every 90 days

Service Management

macOS

launchctl list | grep cc-bridge              # status
launchctl unload ~/Library/LaunchAgents/com.pandanpc.cc-bridge.plist  # stop
launchctl load   ~/Library/LaunchAgents/com.pandanpc.cc-bridge.plist  # start

Linux

systemctl --user status  cc-bridge    # status
systemctl --user restart cc-bridge    # restart
systemctl --user stop    cc-bridge    # stop

Windows

Get-ScheduledTask PandaNpc-cc-bridge         # status
Start-ScheduledTask PandaNpc-cc-bridge       # start
Stop-ScheduledTask PandaNpc-cc-bridge        # stop

Uninstall

# macOS / Linux
curl -fsSL https://pandanpc.com/cc-bridge/uninstall.sh | sh

# Windows
Stop-ScheduledTask PandaNpc-cc-bridge
Unregister-ScheduledTask PandaNpc-cc-bridge -Confirm:$false
Remove-Item -Recurse $env:USERPROFILE\.pandanpc\cc-bridge

Troubleshooting

"Bridge not online"

Check if cc-bridge is running on your server:

# macOS / Linux
tail -f ~/.pandanpc/cc-bridge/logs/stderr.log

# Windows
Get-Content $env:USERPROFILE\.pandanpc\cc-bridge\logs\output.log -Tail 20

Look for Registered as bridge: <your-id>. If missing, the relay connection failed.

Connection drops frequently

  • Check network stability between cc-bridge and relay server
  • cc-bridge automatically reconnects every 5 seconds on disconnect
  • PandaNpcApp auto-reconnects up to 5 times with 3-second intervals

Service won't start

Common causes:

  • Claude CLI not in PATH → set CLAUDE_BIN=/full/path/to/claude in .env
  • Relay server unreachable → check network / firewall for outbound WSS

Wrong token

Verify the token in PandaNpc matches CC_TOKEN in ~/.pandanpc/cc-bridge/.env