PinchTab runs several isolated Chrome instances at once and drives them over one API. That makes the proxy question a double one. Where does the address go, and how do you give each browser its own? We read release v0.15.2 on 20 September 2026.
One warning before the setting. Most files in this project with proxy in the name are not about your address at all. They are the orchestrator forwarding an API call to whichever instance owns a tab. Only three files concern the browser's egress, and those are the ones below.
Where the setting lives
The proxy is a config block, not a launch flag:
| Field | What it holds |
|---|---|
browser.proxy.server | scheme://host:port, one of http, https, socks4, socks5 |
browser.proxy.username and password | the login, in their own fields, written as a pair |
browser.proxy.bypassList | hosts that go direct, one pattern per entry |
browser.proxy.geo | timezone, locale, country and WebRTC address to match the exit |
The server is the prerequisite. The other keys are kept if you set them first, and they do nothing until a server exists. The tool reports the incomplete block on every config read until you finish it.
The login is the exception to the keep-anything rule. Each field requires the other, so a write carrying only one is refused whichever order you try. Send both in one write:
pinchtab config patch '{"browser":{"proxy":{"username":"bob","password":"s3cret"}}}'
The geo block is worth a note. It aligns the browser's story with the exit address, but only on the CloakBrowser engine, where it maps to native fingerprint flags. Stock Chrome derives nothing from it. We covered that engine separately on our CloakBrowser page.
Why the address alone is not enough
Write the login into the address and PinchTab refuses it:
proxy server "http://user:pass@host:8080" must not include embedded credentials; use the username/password fields
That is deliberate, and the code says why: Chrome rejects credentials in --proxy-server anyway, so the login is delivered over the debugging protocol instead. Chrome is launched with a credential free address and the bridge answers the proxy challenge.
The check is careful about one edge. A path is removed before the at sign is looked for, so an address like http://host:8080/p@th is not mistaken for a login.
Readers of our pydoll page will recognise the opposite choice. That library accepts a login inside the address and cuts it out itself, and we measured three password shapes where the parsing goes wrong. Refusing the input removes the whole class of problem.
What it refuses
The third row is the one we want to praise. A broken proxy server does not launch the browser without a proxy. It is a hard error, and the comment gives the reason in one line: launching anyway "would silently egress traffic from the real IP", which they call the worst failure mode for someone who configured a proxy for anonymity. That is our position too. A setting that quietly does not apply is worse than an error.
The fourth row is the smaller sibling of that care. A bypass pattern is joined with semicolons, so a semicolon inside one entry is rejected rather than silently splitting it.
The last row is the gap. The flag validator reserves --user-agent, --user-data-dir, --headless and several more, and points you at the proper config field for each. It does not reserve --proxy-server. So a proxy flag typed into browser.extraFlags passes validation and reaches Chrome, skipping the checks, the redaction in logs and the login delivery. Use the config block.
One address per browser
Several browsers on several addresses is the reason to run this tool at all. The answer is named targets. Their own documentation is explicit: for several named configurations of one browser with different binaries, proxies or fingerprints, use browser.targets, with browser.defaultTarget and browser.fallbackOrder. Each target carries its own proxy block, and an instance selects a target.
| What you want | What to set |
|---|---|
| One address for everything | browser.proxy |
| A different address per browser | one browser.targets entry per address |
| An address on a browser you attached to | the same block, plus the attach setting below |
Note what a browser costs on a metered line. Each instance is a real Chrome pulling images, fonts and scripts, so ten browsers is ten browsers worth of traffic, not ten times a page of text.
The attached browser does not get your login
PinchTab can attach to a Chrome you started yourself. Your proxy credentials are not sent down that connection unless you turn it on, with security.attach.forwardProxyAuth, which defaults to false.
That default is right. A remote debugging socket is a channel where a password should not travel casually. It also explains an attach that connects cleanly and then fails every request with a proxy login error. Turn it on only when you trust both the browser process and the transport.
Turning it off
One detail in this code deserves its own line, because it is a failure nobody thinks about.
Clearing the proxy server used to report success and change nothing. The empty value was dropped from the rendered config, the patcher preserved whatever was on disk, and the old proxy stayed in effect. Their own comment describes the result exactly: the operator believed egress had stopped going through the proxy while it still did.
It is fixed by writing the cleared server as an empty value so the change reaches the file. Check your version if you have ever turned a proxy off here and wondered.
Which proxy type fits it?
Residential, for the sites that answer a hosting address differently. Our own test is the size of that effect: 4 of 13 answers changed between a server address and a residential one.
Two notes for this tool. An allowed address removes the login question completely, which matters more here than elsewhere: there is no password to store in a config, none to forward over an attach, and none to keep out of a log. On a Residential Premium plan your machine's address can be allowed, up to 150 per plan. And because each instance is a real browser, size the plan for pages rather than for records.
A sticky port suits one browser working through one site. Write a retry either way, because a sticky address can change early when its device leaves the network. The residential proxies page lists the plans, and the plan API manages allowed addresses from code.
What breaks
- Your proxy URL is rejected. It carries a login. Move it into the username and password fields.
- A config write is refused. You sent one half of the login. Send both keys in one write.
- The browser will not start. The server value is malformed, and refusing to start is the intended behaviour.
- An attached browser fails every request. Credentials are not forwarded over an attach by default.
- The geo block seems ignored. It only maps to fingerprint flags on the CloakBrowser engine.
- Traffic still uses an old proxy. Confirm your version, then clear the server and read the config back.
What this page does not cover
We read the release as text and did not run the orchestrator, so we did not start an instance, did not watch a challenge being answered, and did not measure a run's traffic. We did not establish what Chrome does when a proxy flag arrives twice, once from the config and once from extraFlags, so this page says only that the validator does not reserve those flags. We read the proxy config, the login bridge, the flag validator, the Chrome launcher and the config reference closely, and the orchestrator files only far enough to see they are about internal forwarding. The release we read is three weeks old and the repository was pushed to four days ago, so the default branch is ahead of it. We will read it again by 20 October 2026.
Where to go from here
Proxies for pydoll covers the opposite choice, a library that accepts the login inside the address, with the three shapes that break it. Proxies for Maxun covers a third answer, where half a login is dropped in silence. Proxies for CloakBrowser covers the engine that the geo block talks to.
Sources
- The proxy config block, the strict address parser, the refusal to launch without a valid proxy, the pair validation and the fix for clearing a server (internal/config/browser_proxy.go). The login delivery over the debugging protocol, its per target rule and its proxy only challenge check (internal/bridge/runtime/proxy_auth.go). The flag validator and the Chrome launcher (internal/config/chrome_flags.go, internal/browsers/chrome/chrome.go). pinchtab/pinchtab, release v0.15.2 of 26 August 2026, read 20 September 2026.
- The incomplete block behaviour, the pair write, the geo mapping and the attach setting. PinchTab configuration reference, docs/reference/config.md, same release.
- 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. Raw output is kept in the research folder of our OpenClaw page.
- Plans, allowed addresses and per gigabyte pricing. HProxy documentation, hproxy.com/docs, 20 September 2026.
