browser-use-proxyhat 0.1.0

ProxyHat residential proxies for browser-use AI agents — sticky sessions, geo-targeting, rotation.

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.

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:

Option	Env var	Notes
api_key	PROXYHAT_API_KEY	Auto-selects an active sub-user with remaining traffic
sub_user	PROXYHAT_SUBUSER	Pick a specific sub-user by uuid or name (with an API key)
username	PROXYHAT_USERNAME	Explicit gateway proxy_username (skips the API)
password	PROXYHAT_PASSWORD	Explicit gateway proxy_password

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