Lightpanda is a headless browser written from scratch in Zig, and it does not use Chrome's network stack. It uses libcurl. That one fact decides everything about its proxy support, and it makes this the only browser in this series where a proxy login travels in the address and SOCKS5 authentication simply works. We read every setting on this page in release 0.4.1, published on 15 September 2026.
The two flags
lightpanda serve --http-proxy "http://USERNAME:PASSWORD@GATEWAY_HOST:GATEWAY_PORT"
Its own help calls --http-proxy the proxy for all HTTP requests. The second flag is --proxy-bearer-token, which sends a Proxy-Authorization header with a bearer token instead of a password. When a proxy answers with a challenge, Lightpanda sets the credentials as proxy credentials rather than site credentials, and keeps that apart across retries.
What the address may contain
Lightpanda hands the string to libcurl without parsing it, so libcurl's rules apply:
| You write | What happens |
|---|---|
http://host:port | an HTTP proxy |
host:port with no scheme | also an HTTP proxy, the libcurl default |
http://user:pass@host:port | the login is used |
socks5://host:port | a SOCKS5 proxy |
socks5h://host:port | SOCKS5, with hostname resolution at the proxy |
https://host:port | TLS to the proxy itself |
Compare that with the Chrome based tools in this series. There the login is dropped from the flag and answered over the DevTools protocol, and SOCKS5 authentication is not supported at all.
The CDP parameter, and what it really changes
Lightpanda speaks the DevTools protocol, so a client can call the command that creates a browser context and pass a proxyServer. It works, but not the way the name suggests. The code applies it by changing the proxy of the single shared HTTP client. A comment there says exactly that: the client is not inside the browser context, so it assumes there is only one.
Two consequences. Two contexts cannot hold two addresses, so a pool cannot be rotated per context. And the proxyBypassList sent alongside is not implemented: it produces a warning in the log and nothing else, so every request follows the proxy once it is set. The swap itself is also only allowed between requests, since the code refuses to change the proxy while a connection is active.
Which proxy type fits Lightpanda?
Residential, for the sites that refuse a hosting address. In our test of 19 September 2026 a residential address changed four of thirteen answers, while four sites refused both. That test used curl, the same client family Lightpanda builds on, though not Lightpanda itself. The table is on our OpenClaw page.
Both of our line types fit here, which is rare in this series. A generated line with a username and password works directly, because libcurl reads the login out of the address. The plan API can generate up to 5,000 of them, each with its own sticky session. A Residential Premium plan can also allow the server's address, up to 150 per plan, and then the address carries no password at all. Our lines are http by default and socks5 on request, and both are shapes libcurl accepts. Rotating ports change the address, a sticky port holds one, and a sticky address can still change early if its device leaves the network, so let the run retry. The residential proxies page lists the plans.
Since a proxy is set for the whole browser, rotate by restarting it or by swapping the address between navigations, not by opening a second context.
What breaks when the proxy is on
- Navigation hangs after you enable request interception. On versions before the fix of 29 May 2026,
Fetch.enabletogether with--http-proxydeadlocked every navigation. Puppeteer turns that domain on when you ask for request interception, so the trigger is easy to hit without knowing it. - An HTTPS page loads and then disappears. A report from September 2026 describes a proxied HTTPS navigation that reports a timeout and falls back to
about:blank, reproduced with a CONNECT proxy and plain example.com. It is open, so test your version before you build on it. - A second context ignores your address. There is one proxy for the browser.
- Your bypass list does nothing. It is not implemented.
- 407 Proxy Authentication Required. The password is wrong, or the line belongs to another plan. Our 407 guide walks through it.
- Certificate checks are weaker than you think. If you turn off host verification, Lightpanda also stops verifying the proxy's own certificate.
What this page does not cover
We read Lightpanda 0.4.1 and libcurl's documentation as text and did not run the browser. So we did not reproduce either bug above, and we did not measure how sites treat an engine that is not Chrome. Proxy support here is young: in February 2025 a maintainer wrote that the browser did not handle proxies at all, and the request for rotation per page was closed only in July 2026. Releases come about monthly, so we will read these settings again by 19 October 2026.
Where to go from here
Proxies for agent-browser covers a tool that can drive Lightpanda as an engine, and what it passes on. HTTP vs SOCKS5 explains the line types that this browser, unusually, accepts in full. Proxies for nodriver shows the workaround a Chrome based tool needs for the login that Lightpanda takes directly.
Sources
- The proxy flags (src/help.zon, src/Config.zig), the libcurl connection layer (src/network/http.zig), the challenge handling (src/network/HttpClient.zig) and the DevTools target domain (src/server/cdp/domains/target.zig). lightpanda-io/browser, release 0.4.1, 15 September 2026.
- CURLOPT_PROXY documentation. curl, release curl-8_22_0, 2 September 2026.
- Issues 387, 400, 420, 2462 and 3395, and pull request 2468. Lightpanda issue tracker, 2025 to 2026.
- SOCKSv5 authentication and credentials in the proxy flag. The Chromium Authors, net/docs/proxy.md, read 19 September 2026.
- Plans, IP whitelist and sticky sessions; errors; the proxy API. HProxy documentation, hproxy.com/docs, 19 September 2026.
- Our own test of 19 September 2026: plain GET requests to 13 sites and 3 controls, two runs from our server and two through a residential line of our own house plan. Raw output is kept in the research folder of our OpenClaw page.
