Skip to content
Cload Cloud
Developer Tools

Chrome Relay

Drives the user's already-open Chrome session — cookies, SSO, extensions, localhost — through a local CLI bridge. Real-Chrome counterpart to Playwright Browser

View source More in Developer Tools

What Chrome Relay Does

Chrome Relay is a local CLI bridge that enables automation and scripting of your already-open Chrome browser session, preserving all your authentication state, cookies, extensions, and localhost access. Unlike headless browser automation tools like Playwright that spawn isolated browser instances, Chrome Relay connects directly to your running Chrome—meaning you get to leverage your existing login sessions, installed extensions, and development server access without re-authentication or setup overhead.

This skill is particularly valuable for developers and power users who need to automate browser tasks while maintaining full access to their personal Chrome environment. Whether you’re testing against localhost services, need to preserve complex SSO flows, or want to automate tasks that require specific extensions, Chrome Relay bridges the gap between traditional browser automation and your real-world development setup.

How to Install

  1. Install Chrome Relay CLI: Visit https://chrome-relay.kushalsm.com/ and follow the platform-specific installation instructions for your OS (macOS, Linux, or Windows).

  2. Verify Chrome is installed: Ensure Google Chrome is installed and can be launched from your system. Chrome Relay requires your existing Chrome installation.

  3. Start Chrome with remote debugging enabled: Launch Chrome with the --remote-debugging-port flag:

    # macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

  4. Initialize Chrome Relay connection: In a separate terminal, connect the CLI bridge:

    chrome-relay connect --port 9222

  5. Verify the connection: The CLI will confirm connection to your Chrome instance. You’re now ready to send commands to your browser.

  6. Start scripting: Use the Chrome Relay CLI to automate browser actions while your actual Chrome session remains visible and interactive.

Use Cases

  • Localhost development testing: Automate testing against local development servers (http://localhost:3000, etc.) with full access to your dev environment without browser restart or cookie loss
  • SSO workflow automation: Automate workflows that require complex single sign-on authentication; Chrome Relay preserves existing SSO sessions so scripts don’t need to re-authenticate
  • Extension-dependent automation: Run automation scripts that require specific Chrome extensions (ad blockers, productivity tools, dev tools) that wouldn’t be available in headless browser instances
  • CI/CD pipeline integration with real Chrome: Bridge the gap between development and testing by running automation against your actual Chrome profile, browser history, and saved passwords
  • Interactive debugging and testing: Combine manual browser interaction with automated tasks—pause automation to manually test something, then resume automation in the same session

How It Works

Chrome Relay leverages Chrome’s DevTools Protocol (CDP), a low-level interface that enables external tools to control and inspect browser behavior. When you launch Chrome with the --remote-debugging-port flag, Chrome exposes a WebSocket endpoint that remote clients can connect to. Chrome Relay acts as a local CLI bridge that translates your commands into CDP messages and sends them to this endpoint.

Unlike traditional browser automation frameworks that spawn new browser processes (like Playwright or Selenium), Chrome Relay connects to your existing Chrome instance—the one you’ve been using, with all your cookies, cache, extensions, and localhost access intact. This architectural difference means your automation scripts inherit your authentication state, browser preferences, and development environment setup automatically. The CLI bridge translates high-level commands into low-level CDP calls, handling the protocol translation transparently.

The local bridge design means all communication happens on your machine without needing to proxy through external services. Your Chrome instance, the CLI tool, and your scripts all run locally, making this approach ideal for development workflows, localhost testing, and scenarios where you need to preserve your existing browser state.

Pros and Cons

Pros:

  • Preserves authentication state, cookies, and SSO sessions—no re-login needed
  • Full access to installed Chrome extensions and your actual browser environment
  • Works with localhost development servers without additional configuration
  • Simple local architecture with no external dependencies or network proxying
  • Combines manual interaction with automated scripts in the same session
  • Lower learning curve compared to setting up Playwright or Puppeteer projects

Cons:

  • Requires Chrome to be actively running on your machine—not suitable for headless servers or CI/CD without display
  • Less mature ecosystem compared to Playwright or Selenium with fewer libraries and integrations
  • Limited documentation and smaller community compared to established automation tools
  • Not ideal for parallel test execution or multiple concurrent browser instances
  • Browser instance is shared, so concurrent scripts can interfere with each other
  • Automation is tied to your personal Chrome profile and environment setup
  • Playwright Browser - Traditional browser automation framework; use for headless testing and CI/CD environments
  • Puppeteer - Node.js library for controlling Chrome/Chromium; similar to Playwright but more low-level
  • Selenium WebDriver - Classic browser automation tool supporting multiple browsers; heavier than Chrome Relay
  • Chrome DevTools Protocol Documentation - Official specification for the protocol that Chrome Relay uses
  • Cypress - Modern testing framework for web applications; focuses on end-to-end testing rather than general automation

Alternatives

  • Playwright: Comprehensive browser automation supporting headless and headed modes with multiple browser engines; better for isolated test environments but loses your existing session state
  • Puppeteer: Lightweight Node.js CDP client that can connect to Chrome instances; more low-level than Chrome Relay and requires more boilerplate to achieve the same tasks
  • Manual testing + browser macros: For simple repetitive tasks, Chrome extension-based macros (Selenium IDE, iMacros) or built-in browser automation features might suffice without requiring a CLI tool
Glossary

Key terms

DevTools Protocol (CDP)
A low-level interface specification that enables external tools to inspect and control browser behavior. Chrome, Chromium, and Edge all implement CDP, allowing remote clients to send commands and receive events via WebSocket.
Remote Debugging Port
A network port (default 9222) exposed by Chrome when launched with the --remote-debugging-port flag. External tools connect to this port via WebSocket to control the browser instance.
Headless Browser
A browser automation approach that runs without a graphical user interface (GUI), typically spawning a new isolated browser process. Tools like Playwright use headless mode for automated testing and scraping.
SSO (Single Sign-On)
An authentication mechanism that allows users to access multiple services with a single login. Chrome Relay preserves SSO sessions so automation scripts don't need to re-authenticate.
CLI Bridge
A command-line interface tool that translates high-level user commands into lower-level protocol messages. In Chrome Relay's case, it translates CLI commands into DevTools Protocol calls sent to Chrome.
FAQ

Frequently Asked Questions

How is Chrome Relay different from Playwright or Selenium?

Playwright and Selenium spawn brand-new browser instances in isolation, requiring separate authentication and setup. Chrome Relay connects to your existing Chrome session, preserving cookies, SSO state, extensions, and localhost access without any additional setup. Use Chrome Relay when you want to leverage your current Chrome environment; use Playwright for headless, isolated automation.

Do I need to install extensions separately for Chrome Relay to use them?

No. Since Chrome Relay connects to your actual Chrome instance, any extensions already installed in that Chrome profile are automatically available to your automation scripts. This is a major advantage over headless browser automation.

Can I use Chrome Relay for CI/CD pipelines?

Chrome Relay is designed for local development workflows where you have a Chrome instance running on the machine. For headless CI/CD environments without a display, traditional tools like Playwright are better suited. You could use Chrome Relay in CI if you spin up a display server and Chrome instance, but that defeats the simplicity advantage.

Does Chrome Relay work with Chromium or Edge?

Chrome Relay is designed for Google Chrome. While Chromium and Edge use similar architecture and also support the DevTools Protocol, Chrome Relay is optimized for Chrome's specific implementation. Check the documentation for Chromium/Edge compatibility.

How do I authenticate with sites that require SSO when using Chrome Relay?

You don't need to—just log in once in your regular Chrome browser before starting automation. Chrome Relay connects to that authenticated session, so your scripts inherit all existing cookies and authentication tokens. SSO workflows that work in your normal browsing will work in your scripts.

Can multiple scripts connect to the same Chrome Relay instance simultaneously?

Chrome Relay allows multiple connections to the same Chrome instance through a single remote debugging port. However, coordinate concurrent access carefully to avoid scripts interfering with each other's actions (clicking, typing, etc.).

What port should I use with the --remote-debugging-port flag?

The default is 9222. Use any available port on your machine, but make sure it's not already in use. Port 9222 is conventional for Chrome remote debugging, so start there unless you have a conflict.

Does Chrome Relay record or capture sensitive information like passwords?

Chrome Relay communicates through DevTools Protocol with your local Chrome instance. All traffic stays local on your machine. However, like any automation tool with access to your browser, use Chrome Relay responsibly and don't share scripts that capture sensitive data.

More in Developer Tools

All →
Developer Tools

Webapp Testing

Tests local web applications using Playwright for verifying frontend functionality, debugging UI behavior, and capturing screenshots.

ComposioHQ