chrome-remote

Expose your local Chrome browser to a remote server via Cloudflare Tunnel. AI agents (OpenClaw, Claude Code, Playwright, Puppeteer) can then control your real browser — with your real profiles, cookies, and sessions.

Install

npm install -g chrome-remote
# or run directly
npx chrome-remote start

Prerequisites

• Chrome (or Chromium/Edge) installed
• cloudflared — install guide
  • macOS: brew install cloudflare/cloudflare/cloudflared
  • Linux: curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared && chmod +x /usr/local/bin/cloudflared
• Node.js 20+

Quick Start

# Start Chrome + Cloudflare Tunnel
chrome-remote start

# Output:
# === Chrome Remote Ready ===
#   Local CDP:    http://127.0.0.1:9222
#   WebSocket:    ws://127.0.0.1:9222/devtools/browser/xxx
#   Tunnel URL:   https://abc-def-123.trycloudflare.com
#   Remote WS:    wss://abc-def-123.trycloudflare.com/devtools/browser/xxx

Copy the Remote WS URL and use it on your server.

Commands

chrome-remote start [options]   # Start Chrome + tunnel
chrome-remote stop              # Stop everything
chrome-remote status            # Show what's running

Start Options

| Flag | Description | Default | |---|---|---| | -p, --port <number> | Chrome debugging port | 9222 | | -d, --user-data-dir <path> | Chrome profile directory | System default | | --chrome-binary <path> | Path to Chrome binary | Auto-detected | | --headless | Run Chrome in headless mode | false | | --no-tunnel | Skip Cloudflare Tunnel (local only) | false |

Examples

# Use a specific Chrome profile
chrome-remote start --user-data-dir ~/Library/Application\ Support/Google/Chrome/Profile\ 2

# Local-only (no tunnel)
chrome-remote start --no-tunnel

# Headless mode
chrome-remote start --headless

# Custom port
chrome-remote start --port 9333

Using with AI Agents / LLMs

Playwright (Node.js)

import { chromium } from 'playwright';

// Connect to your real Chrome via the tunnel
const browser = await chromium.connectOverCDP(
  'wss://abc-def-123.trycloudflare.com/devtools/browser/xxx'
);

// Use it like normal — but it's YOUR Chrome with YOUR sessions
const context = browser.contexts()[0]; // existing browser context
const page = context.pages()[0] || await context.newPage();

await page.goto('https://github.com'); // already logged in!

Puppeteer

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://abc-def-123.trycloudflare.com/devtools/browser/xxx'
});

const page = await browser.newPage();
await page.goto('https://example.com');

Claude Code / OpenClaw / Coding Agents

If your AI agent needs to browse with your real Chrome:

1. Run chrome-remote start on your local machine
2. Give the agent the Remote WS URL
3. Agent connects via Playwright/Puppeteer and has access to your logged-in sessions

Example prompt for an AI agent:

Connect to my Chrome browser at wss://abc-def-123.trycloudflare.com/devtools/browser/xxx
using Playwright's connectOverCDP. Then go to GitHub and check my notifications.

CDP (raw Chrome DevTools Protocol)

# List open tabs
curl https://abc-def-123.trycloudflare.com/json/list

# Get browser version
curl https://abc-def-123.trycloudflare.com/json/version

# Connect via WebSocket for full CDP control
wscat -c wss://abc-def-123.trycloudflare.com/devtools/browser/xxx

What AI agents CAN do through this:

• Navigate to URLs
• Click, type, scroll, take screenshots
• Read page content and DOM
• Execute JavaScript on pages
• Open/close/switch tabs
• Intercept network requests
• Access cookies and localStorage
• Use your existing login sessions

What they CAN'T do (yet):

• Attach to tabs you manually opened before starting chrome-remote
• Survive Chrome restarts without re-running start
• Pick specific tabs to share (it's all-or-nothing)

How It Works

Remote Server (AI Agent / Playwright)
        ↓ WebSocket (CDP)
Cloudflare Tunnel (encrypted, outbound-only)
        ↓
Your Local Machine
        ↓
chrome-remote CLI → Chrome with --remote-debugging-port

1. CLI launches Chrome with remote debugging enabled
2. Cloudflare Tunnel creates a secure outbound connection
3. Remote server connects to Chrome via the tunnel URL
4. All communication uses the standard Chrome DevTools Protocol

Security:

• No inbound ports opened on your machine
• Connection is outbound-only via Cloudflare
• Tunnel URL is random and temporary (quick tunnels)
• For persistent setups, use Cloudflare Access policies

Config

State is stored in ~/.chrome-remote/state.json (PIDs, ports, tunnel URL).

License

MIT