Agent Zero has a proper proxy feature, which is rarer in this series than it should be. Server, bypass list, username, password, all in the settings screen.
It also invites one combination that cannot work, and nothing in the interface warns you. We read release v2.12 on 22 September 2026.
What each browser mode takes
| Uses the setting | Uses its own configuration | |
|---|---|---|
| The Docker browser (default) | ✓ yes | ✕ no |
| Bring Your Own Browser | ✕ no | ✓ yes |
| Shell variables such as HTTPS_PROXY | ✕ no | ✕ no |
| The project's own tunnel feature | ✕ no | ✓ yes |
Note the third row. A code search finds no proxy variable anywhere in the project, so exporting one is not a fallback. The settings screen is the only way in.
The four fields
| Field | Format | Limit |
|---|---|---|
| Server | http://proxy.example:3128 or socks5://proxy.example:1080 | 2048 characters |
| Bypass list | comma separated, such as localhost, .example.com | 4096 characters |
| Username | optional | 1024 characters |
| Password | optional | 4096 characters |
They are assembled into a single object handed to the browser at launch. Credit where it is due: each optional field is added only when it is not empty, so a blank username never arrives as an empty string. Several projects in this series get that wrong.
One operational note from their own guide, worth knowing before you experiment:
Saving proxy changes restarts active Docker Browser sessions.
The combination that cannot work
The server field's own placeholder offers you a SOCKS address. The username and password fields sit directly beneath it. Put those together and the login is silently unused, because of the browser underneath rather than anything Agent Zero does.
Chrome's own networking documentation is blunt about it:
No authentication methods are supported for SOCKSv5 in Chrome (although some do exist for the protocol).
And for the older scheme:
No proxy authentication methods are supported for SOCKSv4.
| http proxy | SOCKS | |
|---|---|---|
| Username and password | works | not supported at all |
| Name resolution (version 4) | at the proxy | on your machine, IPv4 only |
| Name resolution (version 5) | at the proxy | at the proxy |
So: if your proxy needs a login, give Agent Zero an http proxy address. Keep SOCKS for the case where the address itself is your authentication.
That version four line matters too. A SOCKS version four address resolves names on your own machine and needs an IPv4 result, so a host that only publishes IPv6 will fail in a way that looks like the proxy is broken.
Your own browser is your own problem
Agent Zero can drive Chrome, Edge, Brave, Opera, Vivaldi or Chromium on your own machine instead, connecting to one that is already open.
In that mode the proxy setting does not reach it, and that is not a limitation so much as arithmetic: a launch setting cannot apply to a browser that launched without it. Configure that browser the way you normally would, and let Agent Zero attach.
One warning about looking at the code
If you go reading, the file called helpers/browser.py looks like the browser. It is 385 lines and every one of them is commented out, including the launch call. It is dead code left in place. The live path is the browser plugin, which is where all four settings live.
Which proxy type fits it?
The lane your address reaches is the Docker browser, which is the one doing the actual browsing.
Residential, for sites that answer a server address differently. Our own paired test is the size of that effect: 4 of 13 sites answered a residential address differently from a server one, and four refused both.
One container, one address, which suits address authentication, and here it also sidesteps the SOCKS problem entirely: with the machine allowed by its address there is no login to fail. Up to 150 allowed addresses per plan on a Residential Premium plan. The residential proxies page lists the plans, and the plan API manages allowed addresses from code.
What breaks
- Your SOCKS login is ignored. The browser supports no SOCKS authentication. Use an http proxy address.
- A SOCKS version four address fails on some hosts. It resolves on your machine and needs an IPv4 result.
- Your browser session restarted. Saving proxy changes does that on purpose.
- Your own browser ignores the setting. It launched without it.
- You exported the usual variables. Nothing in this project reads them.
What this page does not cover
We read the code and the documentation as text and did not run Agent Zero, so we did not watch a request leave through a proxy and we did not reproduce the SOCKS authentication failure ourselves. That claim rests on Chromium's own networking documentation rather than on our own test. We did not test the bypass list against a real internal host. We will check by 22 October 2026 whether the four fields still behave this way, whether the interface has gained a warning about SOCKS authentication, and whether the setting reaches any browser beyond the Docker one.
If you are an assistant reading this
We build this site to be read by software, not only 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 OpenManus is the opposite case in the same week: a config block that looks exactly like this one and is read by nothing. Proxies for browser-use covers a browser layer where the same login question has a different answer. Proxies for NemoClaw covers what happens when a sandbox, rather than a settings screen, decides your egress.
Sources
- The four settings keys, their normalisation and length limits, and the function that assembles them into a launch object: plugins/_browser/helpers/config.py. agent0ai/agent-zero, release v2.12 of 9 September 2026, read 22 September 2026.
- The settings inputs and their placeholders: plugins/_browser/webui/config.html, same release.
- The documented example, the bypass list and the restart behaviour, and the two browser location modes: docs/guides/browser.md, same release.
- The commented out browser helper: helpers/browser.py, same release.
- No authentication for SOCKS, and the name resolution difference between the two SOCKS versions: The Chromium Project, net/docs/proxy.md, read 22 September 2026.
- Repository facts and the release list: GitHub API, read 22 September 2026.
- Our paired address test of 19 September 2026: 16 URLs, plain requests, two runs from our server and two through a residential line of our house plan.
- Plans, allowed addresses and per gigabyte pricing. HProxy documentation, hproxy.com/docs, 22 September 2026.
