Obscura is a headless browser written in Rust for agents and scrapers, and it takes a proxy in a single global flag. The flag is the easy part. What makes this tool different is what it deliberately does not read, and what it leaves for you to line up afterwards. We read all of it in release v0.2.2 and in the project's issue tracker on 20 September 2026.
The flag, and the variables that do nothing
obscura fetch https://example.com --proxy http://USER:PASS@GATEWAY_HOST:GATEWAY_PORT
obscura serve --proxy socks5://GATEWAY_HOST:GATEWAY_PORT
The flag is global. It works before or after the subcommand. It covers fetching one page, serving a browser, scraping a list and running the agent server. In a parallel scrape each worker inherits it.
| Where the proxy comes from | What happens |
|---|---|
--proxy on the command line | used, for every scheme |
OBSCURA_PROXY in the environment | used, and keeps the password off the command line |
HTTP_PROXY, HTTPS_PROXY, NO_PROXY | ignored entirely, by design |
| An address the client cannot parse | dropped in silence, requests go out directly |
The third row is the one that costs people an afternoon. The documentation is blunt about it: the tool "does not honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY". If your whole container is wired with those variables, this browser walks straight past them. It also means there is no bypass list, so everything it fetches goes through the address you give it.
The silent drop
The fourth row deserves its own paragraph, because it is the failure you cannot see. The client attaches the proxy only if the address parses, and the branch that handles a parse failure is empty. No error, no warning, no exit code. The run continues, from your own address, and looks exactly like a run that worked.
So check the exit address once at the start, rather than trusting the absence of errors:
obscura fetch https://api.ipify.org --proxy http://USER:PASS@GATEWAY_HOST:GATEWAY_PORT --dump text
If that prints your server's address, the proxy was never applied.
What the proxy covers
Everything the page does, including the requests the page makes itself. That was not always true. In May 2026 the stealth client, the in-page fetch and the module loader all went out directly while the navigation used the proxy. Those paths were plumbed one by one, and the address is now shared across the crates on purpose so scripted calls use the same line.
What the flag does not set
There is no automatic matching here. The clock defaults to Europe/Berlin and the coordinates have a fixed default. An address in Chicago with an untouched setup gives you a browser in Berlin, on a connection from Chicago. Set both:
OBSCURA_TIMEZONE=America/Chicago \
OBSCURA_GEOLOCATION="41.8781,-87.6298" \
obscura serve --proxy http://USER:PASS@GATEWAY_HOST:GATEWAY_PORT
Leave the browser profile alone while you do this. The identity is stable by default and rotation is opt-in, for a reason the project states plainly: one address cycling through different identities is itself a signal. If you have pinned a region, a rotated profile stops matching it.
Which proxy type fits it?
Residential, and sticky. The project's own list of what its stealth mode cannot solve ends with address based rate limiting, and the instruction to use proxies for it. That matches what we measured: in our paired test a residential address changed 4 of 13 answers, while four sites refused both addresses. The address is necessary and not sufficient.
Sticky matters more here than in most tools, because you pinned a clock and a set of coordinates by hand. An address that moves underneath them undoes the alignment you just did. Use a sticky port, keep one region per run, and write a retry anyway, since a sticky address can still change early if the device behind it leaves the network.
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. The residential proxies page lists the plans and the plan API manages allowed addresses from code.
Keeping the password out of sight
Worth knowing before you paste a credentialed address into a shared box. On start-up the tool prints the proxy in full, password included, at information level, on both the serving path and the bare command. Supplying it through the environment variable does not change that line, and there is no masking helper in those crates.
The command line used to be worse. Until July 2026 a parallel serve handed the proxy to its workers as an argument, so any local user could read it in the process list. That was reported and fixed the same day. The reason sits in the code beside the fix: a flag is visible in the process list, so the proxy travels through the environment instead.
So prefer the variable over the flag, and keep the logs private. An allowed address removes the password from all three places at once.
What breaks
- The proxy is ignored and nothing says so. A malformed address. Check the exit address with one request.
- Environment variables have no effect. They are not read. Use the flag or the tool's own variable.
- The site sees a mismatch. The clock and the coordinates are still on their defaults.
- A rotated profile stops matching a pinned region. Turn rotation off when you pin anything.
- SOCKS5 refused to navigate on one platform. Reported on macOS in May 2026 and closed; if you meet it, the HTTP port is the way around.
- A dead proxy is a dead run. There is no automatic fallback to a direct request, which is the safer behaviour anyway.
What this page does not cover
We read the documentation and the Rust source as text and did not run the browser. So we did not measure what a session spends through a proxy, and we make no claim about which sites it passes. The silent drop follows from an empty failure branch in the client, not from a run of our own. The start-up line is read in the source, not captured from a log. Our paired address test used plain requests, not this engine. The project pushes daily, so we will read these settings again by 20 October 2026.
One more thing worth saying out loud: most of the guidance you will find around this tool is written by proxy sellers, several of whom pay for placement in its own readme. Read those pages knowing that, ours included.
Where to go from here
Proxies for Lightpanda covers the other new headless engine, where the login travels in the address. Proxies for CloakBrowser covers a patched Chromium that does match the clock to the address automatically. How websites detect proxies explains the signals both of them are lining up.
Sources
- The proxy flag, the stealth limits, the clock and the coordinates (docs/Configure-stealth-and-proxies.md). The ignored environment variables (docs/Environment-variables.md). The proxy branch in the network client (crates/obscura-net/src/client.rs). The start-up lines and the worker environment (crates/obscura-cli/src/main.rs). h4ckf0r0day/obscura, release v0.2.2 of 5 September 2026, read 20 September 2026.
- Issue 139 on the request paths the proxy did not reach. Issue 366 on the password in the process list, and its fix. Issue 160 on SOCKS5 navigation, and issue 491 on the ignored environment variables. Obscura issue tracker, read 20 September 2026.
- Plans, allowed addresses and sticky sessions. HProxy documentation, hproxy.com/docs, 20 September 2026.
- Our own paired test of 19 September 2026: 16 URLs, plain requests, two runs from our server address and two through a residential line of our house plan. Raw output is kept in the research folder of our OpenClaw page.
