How to Bind Zendriver to a Specific Host and Port: Complete Configuration Guide

Supply the host and port arguments to zendriver.core.util.start() or create a Config(host=..., port=...) instance to bind Zendriver to a specific network interface and TCP port, which translates to --remote-debugging-host and --remote-debugging-port Chrome flags.

When automating browsers with the cdpdriver/zendriver library, controlling the network binding is essential for remote debugging scenarios and parallel test execution. Binding Zendriver to a specific host and port allows you to specify exactly which network interface the Chrome DevTools Protocol (CDP) listens on, or attach to an already-running browser instance.

Understanding Host and Port Configuration in Zendriver

Where Parameters Are Defined

In zendriver/core/config.py, the Config class constructor accepts host and port parameters with default values of AUTO. The __init__ method stores these values at lines 41-45, making them available for the entire configuration lifecycle.

How Chrome Flags Are Generated

The Config.__call__ method (lines 217-221 in zendriver/core/config.py) transforms these parameters into Chrome command-line arguments. When self.host or self.port are explicitly set, the method appends --remote-debugging-host= and --remote-debugging-port= flags to the launch arguments.

Methods to Bind Zendriver to a Specific Host and Port

Using the start() Convenience Function

The simplest approach uses zendriver.core.util.start(), which forwards host and port values directly to a fresh Config instance (lines 31-44 in zendriver/core/util.py). This method handles browser creation while applying your network binding specifications.

Attaching to an Existing Chrome Instance

When both host and port are provided, Zendriver assumes you want to connect to an already-running Chrome process rather than launch a new one. As documented in zendriver/core/util.py (lines 65-70), this behavior skips the launch step and attaches directly to the remote debugging endpoint at the specified address.

Direct Config and Browser Creation

For advanced use cases, instantiate Config directly with your host and port parameters, then pass it to Browser.create(). This low-level approach, implemented in zendriver/core/browser.py, gives you full control over the configuration while maintaining the network binding capabilities.

Practical Code Examples

Launch Fresh Chrome with Custom Binding

import asyncio
from zendriver.core.util import start

async def main():
    # Bind the new Chrome instance to 127.0.0.1:9223

    browser = await start(host="127.0.0.1", port=9223, headless=False)
    
    tab = await browser.main_tab.new_page()
    await tab.goto("https://example.com")
    print(await tab.title())
    
    await browser.stop()

asyncio.run(main())

The host and port arguments are passed straight to Config, causing Chrome to receive --remote-debugging-host=127.0.0.1 and --remote-debugging-port=9223.

Attach to Existing Chrome Process

import asyncio
from zendriver.core.util import start

async def attach():
    # Connect to Chrome started manually with:

    # google-chrome --remote-debugging-address=0.0.0.0 --remote-debugging-port=9333

    browser = await start(host="0.0.0.0", port=9333)
    
    print("Connected to existing Chrome instance")
    await browser.stop()

asyncio.run(attach())

Because both host and port are supplied, Browser.create() skips the launch step and attaches directly to the remote debugging endpoint.

Direct Config Usage

import asyncio
from zendriver.core.config import Config
from zendriver.core.browser import Browser

async def manual():
    cfg = Config(host="localhost", port=9242, headless=True)
    browser = await Browser.create(cfg)
    
    # Your automation code here

    
    await browser.stop()

asyncio.run(manual())

Summary

• Supply host and port parameters to start() or Config() to bind Zendriver to specific network interfaces.
• Zendriver translates these values to --remote-debugging-host and --remote-debugging-port Chrome flags via Config.__call__ in zendriver/core/config.py.
• When both parameters are provided, Zendriver attaches to an existing Chrome process rather than launching a new browser instance.
• Use zendriver.core.util.start() for convenience, or Config + Browser.create() for advanced control.

Frequently Asked Questions

What happens if I only specify the port without a host?

If you provide only the port parameter without an explicit host, Zendriver passes the port value to Chrome but may use default binding behavior for the network interface. To ensure predictable remote access, always specify both host (e.g., "0.0.0.0" for all interfaces) and port.

Can I bind Zendriver to 0.0.0.0 for remote connections?

Yes. Setting host="0.0.0.0" in your Config or start() call binds the Chrome DevTools Protocol to all available network interfaces, allowing remote machines to connect to the debugging port. Ensure your firewall and security groups permit access to the specified port.

How do I verify which host and port Zendriver is using?

Check the browser.config object after initialization. The host and port attributes reflect the values passed to Config.__init__ in zendriver/core/config.py. If you specified AUTO (the default), inspect the actual Chrome process command line or check which ports are listening using system tools like netstat or lsof.

Does specifying both host and port prevent Chrome from launching?

Yes. According to the start() implementation in zendriver/core/util.py (lines 65-70), when both host and port are explicitly provided, Zendriver assumes you want to attach to an existing Chrome instance rather than launch a new browser process. It skips the launch step and connects directly to the remote debugging endpoint at the specified address.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}