Skip to content

Proxies for Lightpanda: the browser that takes the login

Set a proxy in Lightpanda 1.0.3: --http-proxy with a login or SOCKS5, why the CDP proxyServer changes the whole browser, and a login fault on redirects.

Billal AinaouiSeptember 19, 2026Updated November 11, 20266 min read

Proxies for Lightpanda: the browser that takes the login

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 writeWhat happens
http://host:portan HTTP proxy
host:port with no schemealso an HTTP proxy, the libcurl default
http://user:pass@host:portthe login is used
socks5://host:porta SOCKS5 proxy
socks5h://host:portSOCKS5, with hostname resolution at the proxy
https://host:portTLS 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 0.4.1 against a Chrome based tool
LightpandaChrome based tool
Login inside the proxy addressyesno
SOCKS5 with a username and passwordyesno
Proxy bypass listnoyes
A different proxy per browser contextnoyes
Source: Lightpanda 0.4.1: src/help.zon, src/network/http.zig, src/server/cdp/domains/target.zig; libcurl CURLOPT_PROXY at curl-8_22_0; Chromium net/docs/proxy.md; read on September 19, 2026 · hproxy.comProxy.

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.enable together with --http-proxy deadlocked 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.continueWithAuth could 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=json returns 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.

Frequently asked questions

How do I use a proxy with Lightpanda?

Start it with --http-proxy and an address, for example lightpanda serve --http-proxy http://USER:PASS@HOST:PORT. The value goes straight to libcurl, which accepts a login inside the URL and the socks4, socks4a, socks5 and socks5h schemes as well as http and https.

Can the address carry a username and password?

Yes. That is the main difference from a Chrome based tool, which drops a login from its proxy flag and needs a separate handler for the challenge. libcurl sends the login from the address as Basic authentication.

Does SOCKS5 work?

Yes, with a login too. Write socks5:// or socks5h:// in the address. The h form leaves hostname resolution to the proxy. Chrome supports no SOCKS5 authentication at all, so a tool built on it cannot do this.

Can I give each browser context its own proxy?

No. The CDP command that creates a browser context accepts a proxyServer, but Lightpanda applies it to the browser's one HTTP client, as its own code comment says, and a connection holds one context at a time. The proxyBypassList parameter next to it is ignored.

What breaks when a proxy is on?

Check three things against your version. Request interception with a proxy deadlocked navigation until a fix in May 2026. From 0.2.8 to 1.0.3 a proxy login answered over the DevTools protocol could follow a redirect to the website, fixed in 1.0.4-rc1. And a report from September 2026 says a proxied HTTPS page can fall back to about:blank after a timeout.

Proxies that don't die mid-job

Residential, ISP, datacenter and mobile, verified by the same engine that runs tens of millions of checks. They read as a real device and hold up under load. Pay as you go, and your balance never expires. $0.23/GB is the 10,000 GB+ rate; a single gigabyte is $0.50/GB, with no minimum order.

129M+ proxy checks run · 100+ countries · HTTP / HTTPS / SOCKS · re-checked every few minutes · no signup

HProxy.

Honest guides and comparisons on proxies, scraping and staying unblocked, from the team that runs the network.

RSS feed