browser-use-proxyhat

Route browser-use AI agents through ProxyHat residential proxies — a sticky residential IP pinned for the whole agent session, plus geo-targeting and rotation.

[!TIP] Recommended proxies — ProxyHat residential IPs. Every feature in this package is tested end-to-end against ProxyHat and works great. First-class integration; also works with any proxy, or none.

Why

Browser agents driving a real browser from a datacenter IP get flagged, CAPTCHA-walled, and blocked. This package plugs ProxyHat's residential IPs (50M+ across 148+ countries) into any browser-use agent through its first-class proxy= option — one pinned residential IP for the whole session by default, so cookies and fingerprint stay consistent while the agent works. No fork, no boilerplate.

Install

pip install browser-use-proxyhat

browser-use is a peer dependency — bring your own version (and its Playwright browser). proxyhat_proxy() (the proxy dict builder) works on its own; proxyhat_browser_session() needs browser-use installed:

pip install browser-use-proxyhat browser-use

Quick start

from browser_use import Agent, ChatOpenAI
from browser_use_proxyhat import proxyhat_browser_session

# An API key auto-selects an active residential sub-user:
agent = Agent(
    task="Find the cheapest flight from SFO to Tokyo next month.",
    llm=ChatOpenAI(model="gpt-4o-mini"),
    browser_session=proxyhat_browser_session(country="us"),  # sticky US IP for the whole session
)
await agent.run()

Get an API key at proxyhat.com.

Just want the proxy dict for your own Browser / BrowserSession / BrowserProfile?

from browser_use import BrowserSession
from browser_use_proxyhat import proxyhat_proxy

session = BrowserSession(proxy=proxyhat_proxy(country="de", sticky="1h"))
# proxyhat_proxy(...) -> {"server": "http://gate.proxyhat.com:8080", "username": ..., "password": ...}

Credentials

Pass them explicitly or via environment variables — options win over env:

Targeting

proxyhat_browser_session(
    protocol="http",   # or "socks5"
    country="us",      # ISO code or "any" (default)
    region="california",
    city="new_york",
    filter="high",     # AI IP-quality tier
    sticky="30m",      # session lifetime (default); sticky=False rotates every request
    headless=True,     # any extra kwarg is forwarded to BrowserSession
)

Sticky IP per agent session (default)

A browser agent takes many steps against the same site — logging in, clicking, scrolling. If the exit IP changed mid-session the site would see a user teleporting between cities and block it. So this package is sticky by default: one residential IP is pinned for the whole BrowserSession (sticky="30m", renewed as the agent works), keeping cookies and fingerprint coherent.

Want a fresh IP on every request instead (e.g. many independent one-shot fetches)? Turn stickiness off:

proxyhat_browser_session(country="us", sticky=False)  # rotating residential IP per connection

Set a custom lifetime with sticky="2h".

How it works

proxyhat_proxy(...) resolves your gateway credentials (via the official proxyhat SDK — an API key auto-picks an active sub-user, or pass username/password), then builds a Playwright-style proxy dict: server is the ProxyHat gateway (http://gate.proxyhat.com:8080, or socks5://…:1080), and username carries ProxyHat's targeting grammar (<user>-country-us-sid-<id>-ttl-30m). proxyhat_browser_session(...) passes that dict to browser-use's proxy= parameter on a BrowserSession — which browser-use hands to Playwright. A sticky username pins one residential IP; a rotating one makes the gateway hand out a fresh IP per connection.

License

MIT © ProxyHat