Browser proxy Docs menu

Docs

Browser proxy: a home connection for your bots' browser

Sites treat a datacenter address, like a VPS, differently from a home one: more CAPTCHAs and blocked sign-ins. kwant can send the bots' browser, and only the browser, out through a proxy, so sites see the proxy's connection. It's off until you set it.

Turn it on

Set KWNT_BROWSER_PROXY where kwant runs:

ValueWhat it means
socks5://host:portSOCKS5. The proxy looks up site names, so your own resolver never sees which sites the bots open.
socks5h://host:portThe same as socks5.
http://host:port, https://host:portAn HTTP or HTTPS proxy.

KWNT_BROWSER_PROXY_BYPASS adds hosts that skip the proxy, separated by ; or ,, in Chromium's form: example.com, *.corp, 10.9.0.0/16.

kwant's own services always skip the proxy: laya, kwnt, browser, localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 and 169.254.0.0/16. So private networks can't be reached through the proxy. List a host in the bypass only if it should go direct.

Where kwant runs

  • Docker compose. Put the value in .env next to docker-compose.yml (or in the shell), then run docker compose up -d browser kwnt. The browser container and kwnt doctor both read it.
  • kwant starts its own browser container (VM mode without compose). The setting goes into the container. Changing or removing it replaces the container the next time a bot opens the browser, and open pages close once.
  • Local mode (Chrome on your own computer). kwant starts its Chrome with the proxy. If that Chrome is still running from an earlier start, close it once so the next start picks the setting up.
KWNT_BROWSER_PROXY=socks5://172.17.0.1:1080

From a container, the Docker host is 172.17.0.1 on the default bridge. A proxy that listens only on the host's 127.0.0.1 can't be reached from the container: run a relay on 172.17.0.1, or use a proxy that listens on the bridge address.

No user names or passwords

kwant refuses a value with a user name or password in it, like socks5://user:pass@host:port. Chromium can't sign in to a SOCKS proxy at all, and a password in a command line or a container's settings would leak. Use a proxy that trusts the network it's reached from: a relay on the Docker bridge, or a WireGuard-to-SOCKS helper next to kwant. The refusal never repeats what you typed.

Check it

docker compose exec kwnt kwnt doctor

The Browser proxy line is OK when the proxy answers and a request through it leaves from a different address than a direct one, and it shows both addresses. It warns when the address is the same (the proxy doesn't go anywhere else) or the test request fails. It fails when the proxy doesn't answer or the value can't be used.

What it doesn't change

  • Only the browser uses the proxy. The AI accounts' traffic and kwant's own downloads go direct.
  • A reverse proxy hop, WebRTC and the sites' own fingerprinting still exist. A home address helps, but it doesn't make the browser invisible. When a site still asks if you're human, you solve it in the browser panel.

More on the browser itself, Local and VM mode and your own Chromium service: AI agent browser.