browsefleet (Python SDK)

Official Python SDK for BrowseFleet, the open-source cloud browser API for AI agents.

One runtime dependency (httpx). Sync + async clients in one import. Full type hints with py.typed. Tested on Python 3.10, 3.11, 3.12, 3.13.

Working in this repo with an AI agent? Read skill.md first. It teaches Claude Code, Cursor, Aider, or any coding agent how to set up, run, test, and contribute to this repo with no further instruction.

Install

pip install browsefleet

The SDK needs a running BrowseFleet server. Follow the server repo's Quick start to spin one up via Docker or local Node dev.

Quick start

from browsefleet import BrowseFleet

bf = BrowseFleet(
    base_url="http://localhost:3000",  # or BROWSEFLEET_URL env var
    api_key="optional-when-server-requires-it",  # or BROWSEFLEET_API_KEY env var
)

# Scrape a page
page = bf.scrape("https://example.com")
print(page.title, page.markdown[:200])

# Take a screenshot
png = bf.screenshot("https://example.com", full_page=True)
with open("example.png", "wb") as f:
    f.write(png)

# Generate a PDF
pdf = bf.pdf("https://example.com", format="A4", print_background=True)

# Spin up a persistent session
session = bf.sessions.create(stealth="full")
bf.sessions.actions(session.id, [
    {"type": "navigate", "url": "https://example.com"},
    {"type": "screenshot"},
])
bf.sessions.release(session.id)

# Vision-based agent task
result = bf.agent.run(
    task="Extract the most expensive product price from this page",
    url="https://example.com/products",
    provider="anthropic",
    max_iterations=10,
)
print(result.success, result.result)

Async client

import asyncio
from browsefleet import AsyncBrowseFleet

async def main():
    async with AsyncBrowseFleet(base_url="http://localhost:3000") as bf:
        page = await bf.scrape("https://example.com")
        print(page.title)

asyncio.run(main())

Both clients share the same public surface. Same methods, same return types, same typed errors.

Features

• Sessions, scrape, screenshot, PDF, agent, profiles, files, CAPTCHA. Full coverage of the BrowseFleet REST surface.
• Operator mode. Sessions can start in human control, hand off to agent via sessions.control().
• Typed errors. AuthError, NotFoundError, RateLimitError, ValidationError, ServerError, all extending BrowseFleetError.
• Auto-retry. Exponential backoff on 429 / 5xx, honors Retry-After. Configurable per client via max_retries.
• Env-var fallback. BROWSEFLEET_URL and BROWSEFLEET_API_KEY are read when not passed explicitly.
• Sync + async. BrowseFleet and AsyncBrowseFleet. Both implement context-manager protocol.
• Typed. py.typed marker, dataclass return types, TypedDict request params. Strict mypy across the source.

Configuration

BrowseFleet(
    base_url="http://localhost:3000",  # or BROWSEFLEET_URL env (default: http://localhost:3000)
    api_key="optional",                # or BROWSEFLEET_API_KEY env (omit if server is authless)
    timeout=60.0,                      # seconds, default 60
    max_retries=2,                     # retries on 429 / 5xx, default 2
)

Examples

See examples/ for runnable mini-projects:

• examples/quickstart/, scrape + screenshot + release
• examples/agent_task/, vision-based agent task
• examples/operator_mode/, human-to-agent handoff via profile + control state machine
• examples/async_client/, the same flows on AsyncBrowseFleet

Contributing

PRs welcome. Read CONTRIBUTING.md and skill.md. Conventional Commits, squash-merge, base branch is master.

Security

Do not file security issues publicly. See SECURITY.md.

License

MIT. See LICENSE.

See also

• BrowseFleet server
• Node SDK
• Marketing site