Skip to main content
View on GitHub
View on PyPI

Installation

Install the Hyperbrowser SDK:

Quick Start

The Hyperbrowser Python SDK supports both synchronous and asynchronous clients.

Synchronous Client

Asynchronous Client

Configuration Options

Both clients accept the same configuration parameters:

Typing Support

The SDK is fully typed end-to-end. In Hyperbrowser 1.0, request parameters are described with TypedDict, so editors autocomplete keys directly inside plain dictionary literals. Import a request type from hyperbrowser.types when you want to annotate a variable:
  • Request parameters: Most methods accept a single typed dictionary. Pass only the fields you need.
  • Field names and aliases: Use Pythonic snake-case keys; the SDK serializes them to API field names automatically (for example, use_ultra_stealth becomes useUltraStealth).
  • JSON Schema and open mappings: User-owned dictionaries, including JSON Schema objects, agent action payloads, environment variables, and storage state values, are preserved rather than recursively renaming their keys. Use the SDK’s snake-case key only for the field that contains the object, such as "output_model_schema" or "schema".
  • Pydantic-generated schemas: Schema fields also accept a Pydantic model class where supported; the SDK generates and dereferences its JSON Schema without mutating your model or input dictionary.
  • Responses: Methods return typed Pydantic models.
  • Backwards compatibility: Existing Pydantic request classes imported from hyperbrowser.models remain supported in 1.0, including their constructors and validation behavior.
Upgrading an existing application? See Migrating to Python SDK 1.0 for side-by-side examples and a compatibility checklist.

Example: Create a session

Sandboxes

Sandbox APIs work in two layers. Sandbox control methods use your API key to create, inspect, connect to, and stop sandboxes. When you create or connect to a sandbox, the SDK also retrieves a sandbox-scoped runtime token and returns an authenticated SandboxHandle. Sandbox VM operations run inside that started sandbox and use the runtime token on the handle automatically. The SDK handles runtime token refreshes for you, so once you have a running SandboxHandle, you can call files, processes, terminal, networking, and snapshot methods without managing runtime auth yourself.

Sandbox Control

Use these methods to inspect existing sandboxes and discover reusable sandbox resources.

Details

List Sandboxes

List Images

List Snapshots

Get Sandbox Info

Lifecycle

Use these methods to create, connect to, and stop sandbox instances.

Create Sandbox

Use client.sandboxes.create(...) to start a sandbox from an image.

Start From A Snapshot

Start a new sandbox from a memory checkpoint.

Connect To A Running Sandbox

Use connect(...) to re-authenticate a running sandbox, refresh its runtime token, and return a SandboxHandle for runtime operations. If you already have a handle, call sandbox.connect() to re-authenticate it in place.

Stop Sandbox

Sandbox VM Operations

These methods operate on the sandbox VM itself when the sandbox is running.

Networking

Expose Port

Unexpose Port

Get Exposed URL

Processes

Run A Command

Use sandbox.exec(...) for one-shot commands. You can also pass a plain string like sandbox.exec("node -v"). Commands are executed through /bin/sh -lc.
If stdout contains JSON, parse it explicitly:

Start A Process

Use sandbox.processes.start(...) for long-running processes.

Get A Process

List Processes

Write Process Stdin

Files

Read Text File

Write Text File

List Files

Watch A Directory

Create Upload URL

Create Download URL

Terminal

Create A Terminal

Use sandbox.terminal.create(...) or the alias sandbox.pty.create(...).

Get A Terminal

Snapshots

Create A Memory Snapshot

Sandbox guides:

Session Runtime Updates

Use session update helpers to change supported settings on an active browser without recreating it.

CAPTCHA Solving

solver_type="visual" enables the visual reCAPTCHA solver. Omit solver_type to use the default automatic CAPTCHA solver configuration.

Manual CAPTCHA Evaluation

Supported captcha and captcha_type values are turnstile, cloudflare-challenge, aliexpress, recaptcha, and amazon.

Integration Examples

Computer Actions

Programmatically control the browser with low-level actions. For the session-id parameter, you can also just pass in the detailed session object itself, and it is actually recommended to do so.

Click

Type Text

Press Keys

Uses the xdotool format for keys: https://github.com/sickcodes/xdotool-gui/blob/master/key_list.csv

Move Mouse

Drag

Scroll

Screenshot

Support