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 withTypedDict, 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_stealthbecomesuseUltraStealth). - 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.modelsremain 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 authenticatedSandboxHandle.
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
Useclient.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
Useconnect(...) 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
Usesandbox.exec(...) for one-shot commands. You can also pass a plain string
like sandbox.exec("node -v"). Commands are executed through /bin/sh -lc.
Start A Process
Usesandbox.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
Usesandbox.terminal.create(...) or the alias sandbox.pty.create(...).
Get A Terminal
Snapshots
Create A Memory Snapshot
- Creating Sandboxes
- Sandbox Lifecycle
- Sandbox Processes
- Local Filesystem
- Sandbox Terminal
- Sandbox Snapshots
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
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 thesession-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.csvMove Mouse
Drag
Scroll
Screenshot
Support
- GitHub Issues: https://github.com/hyperbrowserai/python-sdk/issues
- Email: info@hyperbrowser.ai