# Chrome Debug Mode Chrome Debug Mode refers to running Google Chrome with the remote debugging port enabled, allowing external tools and scripts to connect and control the browser via the [[Chrome DevTools Protocol (CDP)]]. ## Enabling Debug Mode ### Basic Command ```bash google-chrome --remote-debugging-port=9222 ``` ### With Custom Profile (Recommended) Using a separate profile prevents conflicts with your main browser session: ```bash google-chrome --remote-debugging-port=9222 --user-data-dir=/path/to/debug-profile ``` ### Common Flags ```bash google-chrome \ --remote-debugging-port=9222 \ --user-data-dir=/tmp/chrome-debug \ --remote-debugging-address=127.0.0.1 \ --no-first-run \ --no-default-browser-check ``` ## Key Command-Line Flags | Flag | Description | |------|-------------| | `--remote-debugging-port=PORT` | Enable debugging on specified port | | `--remote-debugging-address=IP` | Bind to specific address (default: 127.0.0.1) | | `--user-data-dir=PATH` | Use separate profile directory | | `--headless` | Run without visible UI | | `--disable-gpu` | Disable GPU hardware acceleration | | `--no-sandbox` | Disable sandbox (use with caution) | | `--disable-extensions` | Disable all extensions | | `--incognito` | Start in incognito mode | | `--window-size=W,H` | Set initial window size | ## Security Considerations ### Local Only (Default) By default, Chrome only listens on `127.0.0.1`, which is safe for local development. ### Remote Access To allow remote connections: ```bash --remote-debugging-address=0.0.0.0 ``` ⚠️ **Warning**: Exposing the debug port to the network is dangerous. Anyone who can connect has full control over the browser, including: - Reading all page content and cookies - Executing arbitrary JavaScript - Accessing saved passwords (if logged in) - Capturing screenshots ### Safe Remote Access For secure remote debugging, use: 1. **SSH tunneling**: `ssh -L 9222:localhost:9222 remote-host` 2. **[[Tailscale]]** or VPN: Restrict to trusted network 3. **[[socat]]** bridge with firewall rules Example with socat: ```bash socat TCP-LISTEN:9223,bind=$(tailscale ip -4),reuseaddr,fork TCP:127.0.0.1:9222 ``` ## Connecting to Debug Mode ### Via Browser Navigate to `http://localhost:9222` to see available targets and debug pages. ### Via DevTools Protocol Connect programmatically using WebSocket: ```javascript const ws = new WebSocket('ws://localhost:9222/devtools/browser'); ``` ### Via Tools - **Puppeteer**: `puppeteer.connect({ browserURL: 'http://localhost:9222' })` - **Playwright**: `playwright.chromium.connectOverCDP('http://localhost:9222')` - **chrome-remote-interface**: Node.js CDP client ## Use Cases ### Browser Automation Control Chrome from scripts for testing, scraping, or automation. ### AI Agent Integration Allow AI assistants to browse and interact with web pages via CDP. ### Cross-Device Debugging Debug Chrome on Android or remote machines. ### Performance Profiling Collect performance metrics programmatically. ### Screenshot/PDF Generation Capture pages to images or PDF files. ## Verifying Debug Mode Check if Chrome is running with debug port: ```bash # Check if port is listening ss -tlnp | grep 9222 # Or using curl curl -s http://localhost:9222/json/version ``` Example response: ```json { "Browser": "Chrome/120.0.0.0", "Protocol-Version": "1.3", "User-Agent": "Mozilla/5.0...", "webSocketDebuggerUrl": "ws://localhost:9222/devtools/browser/..." } ``` ## Related - [[Chrome DevTools]] - The visual debugging interface - [[Chrome DevTools Protocol (CDP)]] - The underlying protocol - [[socat]] - Tool for bridging connections - [[Puppeteer]] - Node.js automation library - [[Playwright]] - Cross-browser automation ## References - Chrome DevTools Protocol: https://chromedevtools.github.io/devtools-protocol/ - Chromium Command Line Switches: https://peter.sh/experiments/chromium-command-line-switches/ - Puppeteer Documentation: https://pptr.dev/