remote-cdp

Remote Chrome DevTools Protocol tunnel for headless server development.

The Problem

Developing web applications on a remote server using Claude Code? You've probably hit this wall: Claude Code can't debug your UI because there's no desktop environment to run Chrome.

The Solution

remote-cdp forwards your local Chrome's debugging port to a remote server via SSH. This allows Claude Code (or any CDP-based tool) on the remote server to control your local browser for UI debugging, testing, and automation.

How It Works

┌─────────────────┐         SSH Tunnel          ┌─────────────────┐
│   Local PC      │ ◄──────────────────────────►│  Remote Server  │
│                 │                              │                 │
│  Chrome:9224    │ ◄─── Remote Port Forward ───│  localhost:9222 │
│                 │                              │                 │
│                 │                              │  Claude Code    │
│                 │                              │  + Playwright   │
│                 │                              │    MCP Server   │
└─────────────────┘                              └─────────────────┘

1. Starts Chrome with remote debugging enabled on your local machine
2. Establishes SSH connection to your remote server
3. Creates a reverse tunnel: remote localhost:9222 → local Chrome debug port
4. Claude Code on the remote server connects via Playwright MCP to control your browser

Installation

Build from source

git clone https://github.com/yourusername/remote-cdp.git
cd remote-cdp
go build -o remote-cdp .

Cross-compile

# Linux
GOOS=linux GOARCH=amd64 go build -o remote-cdp-linux .

# macOS
GOOS=darwin GOARCH=amd64 go build -o remote-cdp-macos .

# Windows
GOOS=windows GOARCH=amd64 go build -o remote-cdp.exe .

Usage

Create a profile

remote-cdp create myserver

Follow the prompts to enter SSH credentials and port configuration.

Run a profile

remote-cdp myserver

Or explicitly:

remote-cdp run myserver

Options

remote-cdp myserver --no-chrome    # Use existing Chrome instance
remote-cdp myserver --data-dir /path/to/chrome/profile

Other commands

remote-cdp list                    # List all profiles
remote-cdp delete myserver         # Delete a profile
remote-cdp --help                  # Show help
remote-cdp --version               # Show version

Profile Configuration

Profiles are stored as YAML files in:

• ./profiles/ (relative to executable)
• ~/remote-cdp/profiles/ (user home directory)

Profile format

host: example.com          # SSH server hostname
port: 22                   # SSH port (default: 22)
username: user             # SSH username
password: secret           # SSH password (optional if using key)
key_path: ~/.ssh/id_rsa    # Path to SSH private key (optional)
chrome_port: 9224          # Local Chrome debug port (default: 9224)
remote_port: 9222          # Remote port to expose (default: 9222)

Remote Server Setup

After running remote-cdp, it will check if Claude Code on the remote server is configured. If not, you'll see instructions like:

--- Claude Code MCP Configuration ---
  ✗ Playwright MCP server is NOT configured

  To configure Claude Code on the remote server, add this to:
  ~/.claude.json

  Or run this command on the remote server:
  claude mcp add -s user playwright -- npx @anthropic-ai/mcp-server-playwright@latest --cdp-endpoint http://127.0.0.1:9222
--------------------------------------

Technical Details

Architecture

• Pure Go implementation - No external dependencies like ssh or chrome CLI
• Native SSH - Uses golang.org/x/crypto/ssh for secure connections
• Reverse port forwarding - Opens a listener on the remote server that tunnels back to local Chrome
• Cross-platform - Works on Windows, macOS, and Linux

Security Considerations

• Profile files contain credentials - they are excluded from git by default
• SSH connections support both password and key-based authentication
• Chrome is started with --remote-debugging-port which allows full browser control
• The tunnel only binds to 127.0.0.1 on the remote server (not exposed to network)

Chrome Remote Debugging

Chrome must be started with the --remote-debugging-port flag. On some systems, Chrome requires a separate user data directory when using remote debugging:

chrome --remote-debugging-port=9224 --user-data-dir=/path/to/profile

This tool handles Chrome startup automatically, but you can use --no-chrome if Chrome is already running.

Port Configuration

Port	Location	Purpose
chrome_port (default: 9224)	Local	Chrome DevTools Protocol endpoint
remote_port (default: 9222)	Remote	Exposed to Claude Code/Playwright

Dependencies

golang.org/x/crypto    # SSH client implementation
gopkg.in/yaml.v3       # YAML profile parsing

Use Cases

• Remote web development - Debug UI with Claude Code on headless servers
• CI/CD browser testing - Run browser tests from build servers
• Remote automation - Control a local browser from cloud instances
• Pair programming - Share browser control with remote developers

Requirements

• Go 1.21+ (for building)
• Google Chrome or Chromium
• SSH access to remote server
• Node.js on remote server (for Playwright MCP)

License

MIT