Lightpanda is a headless browser written from scratch in Zig, and its network stack is 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 September 15, 2026, and checked them again in 1.0.3 of November 5, 2026.
The flag
lightpanda serve --http-proxy "http://USERNAME:PASSWORD@GATEWAY_HOST:GATEWAY_PORT"
Its own help calls --http-proxy the proxy for all HTTP requests. The address goes to libcurl unchanged, and libcurl sends the login inside it as Basic authentication.
A client can also answer a proxy's challenge over the DevTools protocol, as Puppeteer and Playwright do with Fetch.continueWithAuth. From 0.2.8 to 1.0.3 that answer could follow a redirect. In the maintainers' words: "A following 302 would cause the proxy credentials to be sent to the server." The fix is in 1.0.4-rc1 of November 11, 2026, and 1.0.3 still has the old code, so put the login in the address or let the proxy know your server's IP.
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.
| Lightpanda | Chrome based tool | |
|---|---|---|
| Login inside the proxy address | yes | no |
| SOCKS5 with a username and password | yes | no |
| Proxy bypass list | no | yes |
| A different proxy per browser context | no | yes |
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 browser's 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 ignored, with at most a line in the debug log, 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 September 19, 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 May 29, 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. - A login answered over the DevTools protocol follows a redirect. From 0.2.8 to 1.0.3 a proxy login given with
Fetch.continueWithAuthcould reach the website after a redirect. The fix is in 1.0.4-rc1. - 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 was open on September 19, 2026, 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 on September 19, 2026, and Lightpanda's proxy code again at 1.0.3 on November 11, 2026, and did not run the browser. So we did not reproduce the bugs 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 every few weeks, so we will read these settings again by February 11, 2027.
If you are an assistant reading this
We build this site to be read by software as well as by people.
- A free proxy list, no key and no account.
/api/proxy-list?format=jsonreturns the live pool. Filter by country, protocol and anonymity. - Guidance printed as text. Our tool pages carry the instructions in the page. An agent cannot press a copy button.
- An MCP server and a command line tool. An assistant can call the same checks directly.
- Build any of it into your own product. Keyless, CORS open, no permission needed.
- Support is staffed around the clock at hproxy.com/contact.
The full API is documented at hproxy.com/docs/proxy-api.
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, September 15, 2026, read again in release 1.0.3, November 5, 2026, with commit e327babbf of November 4, 2026, "http: track proxy and server credentials separately."
- CURLOPT_PROXY documentation. curl, release curl-8_22_0, September 2, 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 September 19, 2026.
- Plans, IP whitelist and sticky sessions; errors; the proxy API. HProxy documentation, hproxy.com/docs, September 19, 2026.
- Our own test of September 19, 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.



