Metadata-Version: 2.5
Name: ant0-browser
Version: 0.1.1
Summary: Playwright SDK for a separately installed Ant0 Browser engine.
Project-URL: Homepage, https://docs.ant0.link/sdk
Project-URL: Support, https://ant0.link/contact
License: BSD-3-Clause
License-File: LICENSE
Keywords: ant0-browser,anti-detect,anti-fingerprint,automation,chromium,farbling,fingerprint,playwright,stealth,ungoogled
Requires-Python: >=3.9
Requires-Dist: maxminddb>=2.2
Requires-Dist: playwright>=1.40
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

<img src="https://ant0.link/icon-192.png" width="64" alt="Ant0 Browser">

# Ant0 Browser SDK for Python

A Playwright-compatible SDK for launching a separately installed Ant0 Browser engine from Python.

[Python SDK guide](https://docs.ant0.link/sdk#python) · [Support](https://ant0.link/contact)

The `ant0-browser` package contains the SDK, not the browser engine, an Ant0 account or licence, or synthetic-identity assets. SDK code is BSD-3-Clause licensed; the engine is installed and licensed separately.

## Before you install

Direct SDK launches require all of the following:

1. Install the Ant0 application and its licensed Ant0 Browser engine.
2. Complete sign-in in the Ant0 application; its local `ant0d` daemon uses that signed-in, licensed state to provide launch tickets.
3. Set `ANT0_BROWSER_BINARY` to the absolute path of that installation's engine executable before starting Python.

The SDK checks that the executable is an Ant0 build; stock Chrome or Chromium is not a substitute. SDK package version `0.1.1` and the installed engine release version are independent.

## Install

```bash
python -m pip install ant0-browser==0.1.1
```

Package metadata declares Python 3.9 or newer. See the qualification table below for tested environments. Do not run `playwright install`: the SDK uses the separately installed Ant0 engine, not Playwright's stock browser downloads.

## Quick start: synchronous API

Save as `example.py` and run `python example.py`. This native-identity example needs no synthetic assets.

```python
from ant0browser import launch


def main():
    browser = launch(identity={"mode": "native"})
    try:
        page = browser.new_page()
        page.goto("https://example.com")
        print(page.title())
    finally:
        browser.close()


if __name__ == "__main__":
    main()
```

## Quick start: asynchronous API

Save as `example_async.py` and run `python example_async.py`.

```python
import asyncio

from ant0browser.async_api import launch


async def main():
    browser = await launch(identity={"mode": "native"})
    try:
        page = await browser.new_page()
        await page.goto("https://example.com")
        print(await page.title())
    finally:
        await browser.close()


if __name__ == "__main__":
    asyncio.run(main())
```

`launch()` creates a temporary profile by default and removes it when the browser closes or the process exits. Use `launch_persistent_context()` when you intentionally need a persistent profile.

## API at a glance

| API | Use | Reference |
| --- | --- | --- |
| `ant0browser.launch(**options)` | Launch a synchronous Playwright browser with the selected identity. | [Python SDK](https://docs.ant0.link/sdk#python) |
| `ant0browser.async_api.launch(**options)` | Async equivalent of `launch()`. | [Python SDK](https://docs.ant0.link/sdk#python) |
| `launch_persistent_context(user_data_dir, **options)` | Launch with an explicitly managed persistent profile. | [Python SDK](https://docs.ant0.link/sdk#python) |
| `serve(**options)` | Start the engine and expose a local CDP endpoint with process controls. | [Python SDK](https://docs.ant0.link/sdk#python) |
| `resolve_geo(proxy=None, quiet=False, timeout=8)` | Optional exit-IP geolocation for identity settings. | [Network details](https://docs.ant0.link/sdk#network) |

Omitting `identity` selects native identity. Captured or synthetic identities and explicit overrides are also available; creating a new synthetic identity requires separately authorized local model or template assets. Those assets are not included in the package.

## Proxy, network, and privacy

Proxy settings for browser launches are optional and follow Playwright's configuration. SOCKS5 username/password authentication is not supported by the engine; use an HTTP(S) proxy with credentials, an unauthenticated SOCKS5 proxy, or Ant0's local relay. GeoIP exit-IP lookups use an HTTP(S) proxy; SOCKS proxies are not supported for that lookup.

| Behavior | Network use |
| --- | --- |
| Launch-ticket handling | When needed, the SDK requests a ticket from the local `ant0d` daemon over loopback. |
| `resolve_geo()` | Only when called. The exit-IP lookup uses the configured proxy; GeoIP data may be fetched directly, and fallback providers may be contacted if the primary lookup is unavailable. |
| Release or optional assets | Only when the corresponding helper is used or an opt-in source is configured. |

See [SDK network details](https://docs.ant0.link/sdk#network) and the [Ant0 Privacy Policy](https://ant0.link/legal/privacy) for more information. `resolve_geo()` is optional; ordinary browser navigation follows the URLs your code opens.

## Runtime and qualification

The package declares Python `>=3.9`. Qualification so far covers the combinations below; the declared minimum is not a claim that every minimum-version/platform combination has been tested.

| Platform | Tested runtime |
| --- | --- |
| Linux | Python 3.12 |
| Windows | Python 3.14.8 |

The engine used for native launch qualification was `154.0.8037.57-ant0.2`.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Engine not found or rejected | Confirm `ANT0_BROWSER_BINARY` points to the executable in an installed Ant0 engine release, not stock Chromium. |
| Launch-ticket rejection (engine exit code 90) | Start Ant0, sign in, and confirm its local daemon can issue a ticket for the installed engine release. The SDK version is not the engine version. |
| Temporary profile or socket path is too long | Set `TMPDIR` (POSIX) or `TEMP`/`TMP` (Windows) to a short, writable local directory before starting Python. |
| SOCKS5 proxy credentials are rejected | Use an HTTP(S) proxy, an unauthenticated SOCKS5 endpoint, or Ant0's local relay. |

## GeoIP attribution

Optional GeoIP uses the IP2Location LITE database ([ip2location.com](https://lite.ip2location.com)), includes GeoLite2 data created by MaxMind ([maxmind.com](https://www.maxmind.com/)), and includes IP geolocation by DB-IP ([db-ip.com](https://db-ip.com)). The merged `geoip-all-in-one` database is GPL-3.0; its data covers country, coordinates, and timezone.

## More information

- [Python SDK guide and API reference](https://docs.ant0.link/sdk#python)
- [Identity options](https://docs.ant0.link/sdk#identity)
- [Network behavior](https://docs.ant0.link/sdk#network)
- [Support](https://ant0.link/contact)
- [Privacy Policy](https://ant0.link/legal/privacy)
