Metadata-Version: 2.4
Name: browser-use-proxyhat
Version: 0.1.0
Summary: ProxyHat residential proxies for browser-use AI agents — sticky sessions, geo-targeting, rotation.
Project-URL: Homepage, https://proxyhat.com
Project-URL: Documentation, https://docs.proxyhat.com
Project-URL: Repository, https://github.com/ProxyHatCom/browser-use-proxyhat
Author-email: ProxyHat <support@proxyhat.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,browser-automation,browser-use,playwright,proxy,proxyhat,residential-proxy,sticky-session
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Requires-Dist: proxyhat>=0.2.0
Provides-Extra: browser-use
Requires-Dist: browser-use>=0.1; extra == 'browser-use'
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# browser-use-proxyhat

Route [browser-use](https://github.com/browser-use/browser-use) AI agents through [ProxyHat](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=browser-use) residential proxies — a sticky residential IP pinned for the whole agent session, plus geo-targeting and rotation.

[![CI](https://github.com/ProxyHatCom/browser-use-proxyhat/actions/workflows/ci.yml/badge.svg)](https://github.com/ProxyHatCom/browser-use-proxyhat/actions/workflows/ci.yml)
[![Compatible with browser-use latest](https://github.com/ProxyHatCom/browser-use-proxyhat/actions/workflows/compat.yml/badge.svg)](https://github.com/ProxyHatCom/browser-use-proxyhat/actions/workflows/compat.yml)
[![PyPI](https://img.shields.io/pypi/v/browser-use-proxyhat)](https://pypi.org/project/browser-use-proxyhat/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 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

```bash
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:

```bash
pip install browser-use-proxyhat browser-use
```

## Quick start

```python
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](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=browser-use).

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

```python
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

```python
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:

```python
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`](https://pypi.org/project/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](https://proxyhat.com)
