CloakBrowser takes a proxy in a single argument, which makes it look like a solved problem. It is not quite. Your login can travel three different ways, and which one you get depends on your operating system and your build rather than on how you wrote the address. This page is the map. We read it all in version 0.5.10 and in the project's own issue tracker on 20 September 2026.
The two shapes
from cloakbrowser import launch
browser = launch(proxy="http://user:pass@GATEWAY_HOST:GATEWAY_PORT")
browser = launch(proxy={
"server": "http://GATEWAY_HOST:GATEWAY_PORT",
"username": "USER",
"password": "PASS",
"bypass": ".internal.example",
})
Both shapes end in the same function. A SOCKS address works in either:
browser = launch(proxy="socks5://user:pass@GATEWAY_HOST:GATEWAY_PORT")
That second one deserves attention. Stock Chrome ignores a login in its proxy flag and supports no SOCKS5 authentication at all. This browser is a patched Chromium, and here a SOCKS5 login is handed to the browser and used. If you have been told for years that SOCKS5 with a password cannot work in a Chromium, this is the exception.
Which route your login takes
| Your proxy | Where the login goes | What it means |
|---|---|---|
| SOCKS5 with a login | into the browser flag, always | works on every build |
| HTTP with a login, build at or above the floor | into the browser flag | sent on the first connection, before any refusal |
| HTTP with a login, build below the floor | into Playwright's own handler | answers a refusal after the fact, and breaks on some proxies |
| No login at all | Playwright's proxy setting | nothing to send |
The floor is a table in the code, one entry per platform:
- Linux x64 and Windows x64: build 146.0.7680.177.5
- Linux arm64, macOS on Apple silicon, macOS on Intel: build 148.0.7778.215.3
Platforms below their floor fall back, and the free macOS default sits below it. Your licence does not change the rule, it only decides which build launches.
Why this matters is the older route's shape. It waits for the proxy to refuse, then answers with your password. A proxy that answers 407 and immediately closes the connection never gets that answer. That exact failure is what moved the login into the browser flag: as the maintainer put it, the flag "sends Proxy-Authorization preemptively on the first CONNECT. No more 407 round-trip". Our 407 guide covers the error itself.
Percent encode the password
This is the trap that costs the most. A user's password contained an equals sign. The address parser cut the password short at that sign, the login failed, and the browser quietly went out directly, from the real address, while the script believed it was proxied.
from urllib.parse import quote
proxy = f"socks5://{quote(user)}:{quote(password)}@GATEWAY_HOST:GATEWAY_PORT"
Recent versions re-encode credentials for you and mention it in an information message, so raise your log level if you want to see it. Encoding it yourself costs one line and removes the question.
There is also a neat test in that thread for telling two failures apart. Run the same address with deliberately wrong credentials. If you get a connection error, the flag was honoured and the fault is your login. If everything still works, the proxy was never used at all.
Matching the clock to the address
A residential address in Warsaw with a browser clock set to Berlin is a mismatch a site can measure. The tool can fix that for you:
browser = launch(proxy="http://user:pass@GATEWAY_HOST:GATEWAY_PORT", geoip=True)
It looks up the address your proxy exits from, reads that address in a city database, and sets the timezone and locale to match. The exit address is reused to replace the WebRTC candidate address, at no extra request. If the lookup fails, the launch fails rather than continuing with a wrong clock.
One condition, and it is not in the documentation. The resolution happens inside the launch call and nowhere else. If you launch once and then give each context its own proxy, which is the usual way people rotate, the timezone and locale stay on whatever the launch address resolved. A contributor opened a pull request to warn about this in May 2026. It is still open, so the shipped version says nothing. Keep one address per browser when the clock matters.
What actually travels through your proxy
We measured the parts the tool fetches. The address lookup is at most three small requests, to three public echo services, and from our server each answered in under two tenths of a second. That costs a few hundred bytes of your traffic, not megabytes. The city database is a different matter: 62.8 MiB, refreshed every thirty days, and fetched outside the proxy you passed. On a metered line that is good news. On a locked down server it is one more host to allow.
The licence call on a paid build goes straight to the project's own server by default. A newer build can route it through your proxy with a flag, which is off on purpose so it never spends your traffic.
Which proxy type fits it?
Residential, because the reason you are here is a site that refuses a server address. The tool changes what the browser looks like; only the proxy changes where it comes from.
Give one browser one address. That is not a general rule of proxying, it is this tool's shape: the clock and locale are matched once, at launch, so an address that changes underneath the browser undoes the match. A sticky port suits that exactly. Rotate between browsers rather than inside one, and let your script retry, because a sticky address can still change early if the device behind it leaves the network.
Nothing here rotates on its own. The project says so plainly: no rotation is built in, bring your own. If you would rather send no password at all, an HProxy Residential Premium plan can allow the machine's address instead, up to 150 per plan, and then none of the three routes above applies to you. The residential proxies page lists the plans and the plan API manages allowed addresses from code.
What breaks
- Plain HTTP pages fail while secure ones work. With a login on the proxy, the credentials go out on secure connections but not on plain ones. The maintainer reproduced it, placed the fix in the browser build, and the issue is still open.
- The browser goes out directly and says nothing. Almost always a password the parser cut short. Encode it.
- A proxy for inspection in front of the browser. Reported as failing in May 2026, with a certificate error for HTTP and no supported proxies for SOCKS5. We did not retest that on the current build.
- The clock does not match the address. A proxy set per context after launch. Move it to the launch call.
- 407 Proxy Authentication Required. On an older build the login is taking the handler route. Move to a build at or above your platform's floor, or allow the machine's address instead.
What this page does not cover
The browser itself is a prebuilt binary that is not in the repository, so everything above about what the browser does with a proxy comes from the library's own capability table and from the maintainer's answers on the tracker, rather than from reading that code. We did not run the browser, so we make no claim about which sites it passes. The inspecting proxy limit rests on a single report from May 2026 against an older version. This project ships often, so we will read the proxy code and those two open issues again by 20 October 2026.
Where to go from here
Proxies for Camoufox covers the other patched browser in this family and its own geo matching. Proxies for nodriver covers the Chrome based tool where a login cannot travel at all. How websites detect proxies explains what these tools are hiding from.
Sources
- The proxy routing (cloakbrowser/browser.py), the per platform floor for inline credentials (cloakbrowser/config.py), the geo resolution and its downloads (cloakbrowser/geoip.py), and the README flag table. CloakHQ/CloakBrowser, tag v0.5.10, read 20 September 2026.
- Issue 182 on the 407 that closes the connection, issue 157 on the password cut short at an equals sign, issue 367 on plain HTTP pages, issue 191 on an inspecting proxy, and pull request 229 on the launch-only geo resolution. CloakBrowser issue tracker, read 20 September 2026.
- Plans, allowed addresses and sticky sessions. HProxy documentation, hproxy.com/docs, 20 September 2026.
- Our own measurement of 20 September 2026: two runs against the three exit address services the tool uses, and one request for the city database, from our server. Raw output is kept in the research folder of this page.
