Chromedp Proxy and How to Use a Proxy with chromedp in 2026
TL;DR
A chromedp proxy is configured when Chrome starts. Pass the endpoint through chromedp.ProxyServer, which maps to Chrome's --proxy-server flag.
Do not put proxy credentials inside ProxyServer. Handle a 407 challenge through the Chrome DevTools Protocol Fetch domain and supply credentials with ContinueWithAuth.
Changing ProxyServer does not rotate an already running browser. Start a new execution allocator for each application-selected endpoint, or use one provider gateway that rotates exits upstream.
Successful navigation is not enough evidence. Read a known DOM marker or authorized IP-check response and confirm the browser used the expected route.
The similarly named chromedp-proxy repository is a CDP logging tool. It is not the setting that routes Chrome's outbound web traffic.
What Is a chromedp Proxy?
A chromedp proxy is an outbound network route attached to the Chrome process that chromedp controls. The official chromedp package documentation describes chromedp as a high-level browser automation library for the Chrome DevTools Protocol. Its ProxyServer allocator option supplies Chrome's proxy-server command-line value before the browser launches.
That lifecycle is the key idea. A proxy is not a per-navigation option on chromedp.Navigate. It belongs to an ExecAllocator, which creates a Chrome process, and every tab or target using that process inherits the route. Chrome sends browser traffic through the endpoint while chromedp continues to drive navigation, clicks, waits, and DOM extraction through CDP.
Search results also surface a project named chromedp-proxy. That repository records and replays CDP messages for debugging; it does not replace chromedp.ProxyServer for outbound HTTP or HTTPS traffic. This guide uses “chromedp proxy” to mean the browser's external network proxy.
Use one when an authorized automation workflow needs controlled egress, location-aware testing, ad verification, public-page monitoring, or isolation between jobs. A proxy changes the route; it does not grant permission to access a destination or make fragile selectors reliable.
For a managed route, Nstproxy Residential Prime Proxies expose standard proxy endpoints that can be attached at the same Chrome-process boundary.
How Proxy Routing Works in chromedp
The route is determined before Chrome starts:
Build allocator options from chromedp.DefaultExecAllocatorOptions.
Add chromedp.ProxyServer("http://host:port").
Create an execution allocator with chromedp.NewExecAllocator.
Create a browser context from the allocator and run navigation actions.
Cancel both contexts when the job ends so Chrome and its resources are released.
The current chromedp release history lists v0.15.1 as the latest release at the time of testing. The examples below pin that version and were compiled with Go 1.26.7 against Google Chrome on August 20, 2026.
For HTTP proxy gateways, a URL such as http://proxy.example:9000 can route both HTTP pages and HTTPS pages. Chrome uses CONNECT for HTTPS destinations. Keep TLS verification enabled; ignoring certificate errors hides configuration problems and weakens the acceptance test.
Prerequisites and Safe Configuration
Create a small Go module and install the tested dependency:
go mod init chromedp-proxy-example
go get github.com/chromedp/chromedp@v0.15.1
Set the Chrome executable, proxy endpoint, and an authorized target through protected runtime configuration:
Use your platform's real Chrome path. Keep endpoints and credentials out of repositories, screenshots, metrics labels, and application logs. The examples fail fast when a required value is missing and place a 20-second bound around the browser task.
Route chromedp Browsers Through Nstproxy
Create an authenticated proxy endpoint, attach it when Chrome starts, and verify the rendered route.
There are three practical methods: start Chrome with one ordinary proxy, answer a proxy-authentication challenge through CDP, or launch separate browser allocators for multiple endpoints. Each complete example below was run against a local purpose-built proxy. The returned body identified the actual listening port, so the checks tested routing rather than only successful browser startup.
Method 1: Start Chrome with One Proxy
Use chromedp.ProxyServer when the endpoint does not require a browser-handled authentication challenge. The allocator options must be complete before NewExecAllocator is called.
package main
import("context""fmt""log""os""time""github.com/chromedp/chromedp")funcmain(){ proxyURL :=mustEnv("PROXY_URL") targetURL :=mustEnv("TARGET_URL") opts :=append(chromedp.DefaultExecAllocatorOptions[:], chromedp.ExecPath(mustEnv("CHROME_PATH")), chromedp.ProxyServer(proxyURL),) allocCtx, cancelAlloc := chromedp.NewExecAllocator(context.Background(), opts...)defercancelAlloc() ctx, cancelBrowser := chromedp.NewContext(allocCtx)defercancelBrowser() ctx, cancelTimeout := context.WithTimeout(ctx,20*time.Second)defercancelTimeout()var body stringif err := chromedp.Run(ctx, chromedp.Navigate(targetURL), chromedp.Text("body",&body, chromedp.ByQuery),); err !=nil{ log.Fatal(err)} fmt.Println(body)}funcmustEnv(name string)string{ value := os.Getenv(name)if value ==""{ log.Fatalf("%s is required", name)}return value
}
The verification endpoint on port 18380 returned basic_proxy_port_18380, and the program printed that exact DOM text. Replace the body print in production with a non-sensitive route marker, rendered title, or expected page element.
Do not rely on Chrome's default executable discovery in a controlled deployment. An explicit path makes local, container, and CI behavior easier to compare. Inspect bypass rules if local or internal destinations unexpectedly avoid the proxy. Nstproxy's Chrome proxy setup guide explains the same browser-level concepts outside Go.
Method 2: Authenticate a chromedp Proxy Through CDP
Chrome does not reliably accept username:password@host:port as a --proxy-server value. Pass a credential-free endpoint to ProxyServer, enable the Fetch domain, and answer only challenges whose source is Proxy. The Chrome DevTools Protocol Fetch domain defines handleAuthRequests and continueWithAuth; the official chromedp authenticated-proxy example uses the same event-driven pattern.
Run it with PROXY_USERNAME and PROXY_PASSWORD supplied by your secret system. In the test, the proxy returned 407 until the Fetch handler provided the correct values; the final DOM marker was authenticated_proxy_port_18381.
The goroutines are intentional. A chromedp event callback must not synchronously invoke another blocking chromedp.Run on the same target. Continue paused requests promptly, restrict credentials to proxy challenges, and cancel the listener after the intended challenge is handled. If the target itself also uses HTTP authentication, build a separate rule instead of sending proxy secrets.
Method 3: Rotate Proxies with a New Browser Allocator
Use a new execution allocator for each application-selected endpoint because ProxyServer is a Chrome process flag. Changing a Go variable cannot reroute a browser that is already running.
With ports 18380 and 18382, the output reported basic_proxy_port_18380 followed by rotated_proxy_port_18382. The cleanup lives inside browseWithProxy, so defer calls execute after every iteration instead of accumulating until a large loop ends.
Starting Chrome per endpoint costs more CPU and latency than reusing a process. For independent jobs, keep concurrency bounded and record a non-secret endpoint ID, start latency, navigation latency, and failure class. For stateful flows, keep cookies, tabs, and proxy route together for the required session. If one gateway can rotate or hold an upstream session, provider-side rotation avoids launching a process solely to change the exit. Compare this model with the process and context choices in the Puppeteer proxy guide.
How to Verify the Proxy Route
Verify route, browser result, and extraction separately. First navigate to an authorized IP-reflection or controlled diagnostic page through the proxy and compare its observed address or route marker with the provider session. Second, require the expected title, element, or application state after JavaScript runs. Third, capture a bounded set of timings and error classes without logging credentials or sensitive page content.
A navigation that returns HTML can still be wrong. Proxy error pages, login pages, consent screens, and block pages may all produce a document. Require a recognizable marker and reject unexpected content before downstream actions. The Playwright proxy troubleshooting guide covers related browser-routing symptoms that also help when isolating Chrome, DNS, authentication, and target-response failures.
For deeper network evidence, listen for CDP Network events and record the main document's URL and status. Keep the checks observable but minimal: high-volume response-body logging can expose data and create noise.
Choosing an Nstproxy Route for chromedp
Nstproxy Residential Prime Proxies fit chromedp workflows that need standard authenticated endpoints, selectable locations, and rotating or sticky sessions on the current product surface. Chrome receives a normal proxy endpoint, so the integration stays in allocator and Fetch-domain code rather than a provider-specific browser SDK.
Use a sticky session when a multi-step browser flow depends on cookies or a stable identity.
Use rotation for independent authorized checks where each job can tolerate a different exit.
Start with measured traffic and compare the current package and pay-per-use models on the Residential Prime pricing page.
Test the exact destination, region, session behavior, and authentication flow before increasing concurrency. Proxy routing does not replace browser waiting strategy or selector validation. The browser automation tools comparison can help if the broader choice between chromedp and another automation stack is still open.
The allocator did not receive ProxyServer, or a bypass rule matched
Build options before NewExecAllocator; inspect bypass rules; verify against a controlled marker.
407 Proxy Authentication Required
The endpoint needs credentials
Enable Fetch auth handling, answer only proxy challenges, and verify secrets without printing them.
Navigation hangs after enabling Fetch
Paused requests were never continued, or the event callback blocked
Handle EventRequestPaused and run continuation actions in goroutines.
Rotation keeps the same exit
The same Chrome process is reused, or the provider session is sticky
Create a new allocator per endpoint, or change the provider's session identifier.
ERR_PROXY_CONNECTION_FAILED
Wrong scheme, host, port, or unreachable endpoint
Test endpoint reachability, confirm the protocol, and use a bounded timeout.
Page loads but selectors fail
The response is an error or alternate page, or the wait is wrong
Inspect title and a known DOM marker; separate routing, rendering, and extraction.
Chrome processes accumulate
Allocator or browser contexts are not canceled
Pair every created context with cleanup at the correct job scope.
Retries should be selective and bounded. Retry transient connection and gateway failures with backoff; do not loop indefinitely on bad credentials, forbidden targets, or structurally invalid content. Quarantine repeatedly failing endpoints and preserve only non-secret diagnostics.
Conclusion
A reliable chromedp proxy setup starts at the Chrome-process boundary. Use chromedp.ProxyServer for an ordinary endpoint, the Fetch domain for a 407 authentication challenge, and a new allocator when your Go application explicitly changes endpoints. Then prove the route with a controlled response and separately validate the rendered page.
Begin with one authorized destination and one proxy. Once route, authentication, cleanup, and page acceptance checks are repeatable, add rotation and concurrency according to measured needs.
Q: Can I put a username and password in chromedp.ProxyServer?
Do not rely on credentials embedded in the proxy-server value. Pass the host and port to ProxyServer, enable Fetch authentication events, and supply secrets with fetch.ContinueWithAuth after a proxy challenge.
Q: Can chromedp change proxies without restarting Chrome?
Not through ProxyServer, because it becomes a Chrome process flag at launch. Start a new execution allocator for another application-selected endpoint, or use a gateway that changes exits while its address remains constant.
Q: Does a chromedp proxy work with HTTPS pages?
Yes. An HTTP proxy normally tunnels HTTPS destinations with CONNECT. Keep certificate verification enabled and confirm that the target sees the intended exit route.
Q: Why does chromedp hang after I enable the Fetch domain?
Fetch pauses matching requests. Continue EventRequestPaused events and avoid blocking the chromedp listener by running continuation actions in goroutines.
Q: Is the chromedp-proxy GitHub project required for outbound proxies?
No. That similarly named project is a CDP logging and replay tool; outbound browser routing uses chromedp.ProxyServer and, when needed, CDP authentication handling.
Marcus Chen
Aug. 20th 2026
110M+ real IPs with 99.9% access success
Blazing-fast average response ~0.5s for high-concurrency tasks
From only $0.1/GB
Get immediate access to premium residential, datacenter, IPv6 and ISP proxy pools.
