GL Browser Use

GL Browser Use is a typed Python SDK for running browser automation tasks through browser-use. It provides a stable client facade, structured stream events, explicit result objects, optional Steel or OpenSandbox browser infrastructure, optional MinIO/S3-compatible recording storage, and bounded retries for recoverable browser-session failures.

Installation

Install the core SDK:

pip install gl-browser-use

Install optional providers only when you need them:

pip install "gl-browser-use[steel]"           # Steel browser infrastructure
pip install "gl-browser-use[opensandbox]"     # OpenSandbox browser infrastructure
pip install "gl-browser-use[infrastructure]"  # All browser infrastructure providers
pip install "gl-browser-use[minio]"           # MinIO/S3-compatible object storage
pip install "gl-browser-use[storage]"         # All object storage providers
pip install "gl-browser-use[full]"            # Infrastructure + storage providers

Use the concrete extras (steel, opensandbox, minio) in application dependency files when you want to pin exactly which provider you depend on. The slot extras (infrastructure, storage, full) are convenience aliases and may include more providers later.

Quick Start

BrowserUseClient supports streaming and non-streaming execution. API keys can be passed directly or read from environment variables.

import asyncio

from gl_browser_use import BrowserUseClient, BrowserUseClientConfig
from gl_browser_use.infrastructure import SteelBrowserInfrastructure
from gl_browser_use.storage import MinIOS3CompatibleStorage


async def main() -> None:
    client = BrowserUseClient(
        config=BrowserUseClientConfig(
            llm_openai_api_key="...",
            page_extraction_llm_openai_api_key="...",
            max_session_retries=2,
            session_retry_delay_in_s=3.0,
        ),
        infrastructure=SteelBrowserInfrastructure(),  # reads STEEL_API_KEY by default
        storage=MinIOS3CompatibleStorage.from_environment(),
    )

    async for event in client.run("Open Hacker News and list five article titles"):
        print(event.content)


asyncio.run(main())

For a single aggregated result:

from gl_browser_use import BrowserUseClient, BrowserUseClientConfig
from gl_browser_use.infrastructure import SteelBrowserInfrastructure

client = BrowserUseClient(
    config=BrowserUseClientConfig(
        llm_openai_api_key="...",
        page_extraction_llm_openai_api_key="...",
    ),
    infrastructure=SteelBrowserInfrastructure(),
)

result = client.run_sync("Open Hacker News and list five article titles")

print(result.status)
print(result.final_output)
print(result.session_id)
print(result.streaming_url)
print(result.recording_url)
print(result.metadata)

Configuration

BrowserUseClientConfig validates required values when the client is created. If llm_openai_api_key or page_extraction_llm_openai_api_key is not passed, both default to OPENAI_API_KEY.

Common client options:

1. llm_openai_model: primary browser-control model. Default: o3.
2. page_extraction_llm_openai_model: page extraction model. Default: gpt-5-mini.
3. sensitive_data: optional browser-use placeholder map. It accepts either a flat placeholder-to-value map or a domain-scoped map. Values are excluded from normal config serialization and redacted from redacted_dict() output.
4. extend_system_message: optional system prompt extension.
5. vision_detail_level: auto, low, or high. Default: auto.
6. llm_timeout_in_s: optional LLM timeout.
7. step_timeout_in_s: per-step browser timeout. Default: 180.
8. agent_kwargs: additional browser_use.Agent constructor arguments. It cannot override SDK-managed arguments such as the task, LLMs, browser session, sensitive_data, or timeouts.
9. enable_cloud_sync: controls browser-use cloud sync. Default: False.
10. logging_level: debug, info, warning, error, or result. Default: info.
11. max_session_retries: recoverable session retries. Default: 2.
12. session_retry_delay_in_s: delay between retries. Default: 3.0.

Sensitive data and Agent options

config = BrowserUseClientConfig(
    llm_openai_api_key="...",
    page_extraction_llm_openai_api_key="...",
    sensitive_data={"username": "example-user", "password": "example-password"},
    agent_kwargs={"use_vision": False, "max_actions_per_step": 2},
)

Keep one configured client per credential scope. Browser-use also accepts domain-scoped sensitive_data maps. Never put real values in logs, serialized configuration, or agent_kwargs.

When supplying sensitive data, restrict browser navigation to the expected domains (for example, through the infrastructure session's browser-use BrowserProfile(allowed_domains=...)) to reduce prompt-injection exfiltration risk. agent_kwargs cannot override browser/session ownership (browser, browser_profile, and browser_session are reserved); configure those controls through the selected infrastructure instead.

Optional provider environment variables:

1. STEEL_API_KEY: used by SteelBrowserInfrastructure() when api_key is not passed.
2. OPENSANDBOX_DOMAIN: OpenSandbox control-plane host. Default: localhost:8080.
3. OPENSANDBOX_API_KEY: required for shared OpenSandbox clusters; optional for local insecure servers.
4. OBJECT_STORAGE_URL: MinIO/S3 endpoint, for example localhost:9001 or https://storage.example.
5. OBJECT_STORAGE_USERNAME: object storage access key.
6. OBJECT_STORAGE_PASSWORD: object storage secret key.
7. OBJECT_STORAGE_BUCKET_NAME: target bucket name.
8. OBJECT_STORAGE_DIRECTORY_PREFIX: optional object key prefix.
9. OBJECT_STORAGE_SECURE: true for HTTPS when the endpoint has no scheme.

Copy .env.example to .env for local development, then load it with your application environment manager.

Runtime API

The client exposes three run methods:

1. run(task): async generator that yields BrowserUseStreamEvent values as work progresses.
2. run_once(task): async method that returns one BrowserUseRunResult and includes emitted events in result.events.
3. run_sync(task): blocking wrapper around run_once() using asyncio.run().

Do not call run_sync() from an already running event loop. Use await run_once() or async for event in run() in async applications.

Cancelling the stream by breaking from async for or calling await stream.aclose() cancels the underlying run task. Browser sessions and infrastructure sessions are released in cleanup.

Result Contract

BrowserUseRunResult contains:

1. status: success, error, or cancelled.
2. task: normalized task string.
3. final_output: final text extracted from the underlying agent, or Task completed when no final text is available.
4. session_id: infrastructure session ID when an external browser session was used.
5. streaming_url: browser debug or streaming URL when available.
6. recording_url: expected recording URL when recording is configured.
7. steps: number of browser-use steps executed.
8. error: terminal error message for error results.
9. events: collected stream events for run_once().
10. metadata: attempt, retry, and recording metadata.

Recording metadata uses these statuses:

1. disabled: infrastructure, storage, or browser context is not available.
2. unsupported: the selected infrastructure does not support recording.
3. unavailable: storage is configured but not available.
4. scheduled: a background recording upload has been scheduled.
5. unknown: recording may have started, but the terminal error did not include enough context to determine the final state.

Streaming Contract

BrowserUseStreamEvent contains:

1. event_type
2. content
3. thinking_and_activity_info
4. is_final
5. tool_info
6. metadata

Important event content values:

1. Receive streaming URL: emitted when a browser debug or streaming URL is available.
2. Receive recording URL: emitted when a recording URL can be resolved.
3. Task completed: emitted for the final successful step.

Activity events encode iframe URLs in thinking_and_activity_info["data_value"] as a JSON string:

{"type": "iframe", "message": "<url>"}

Step events include serialized tool calls in tool_info["tool_calls"].

Retries And Errors

The client retries only classified recoverable browser-session failures, such as browser closure or websocket disconnect messages. Before each retry, it emits a retry status event. Retries are bounded by max_session_retries, so total attempts are max_session_retries + 1.

Non-recoverable task failures return BrowserUseRunResult(status="error"). Recoverable failures that exhaust all attempts raise BrowserUseRetryExhaustedError.

SDK error types:

1. BrowserUseConfigurationError: missing or invalid runtime configuration.
2. BrowserUseDependencyError: optional provider dependency problem.
3. BrowserUseMissingDependencyError: optional provider extra is not installed.
4. BrowserUseExecutionError: execution-time failure.
5. BrowserUseRetryExhaustedError: recoverable session retries were exhausted.

Optional Providers

Optional providers are lazy-loaded. Importing gl_browser_use does not require Steel, OpenSandbox, or MinIO to be installed.

from gl_browser_use.infrastructure import OpenSandboxBrowserInfrastructure, SteelBrowserInfrastructure
from gl_browser_use.storage import MinIOS3CompatibleStorage

SteelBrowserInfrastructure creates Steel browser sessions and provides CDP/streaming URLs.

OpenSandboxBrowserInfrastructure provisions the repo-committed Chrome example image (opensandbox/chrome:latest, built from examples/opensandbox/chrome) through a local or shared OpenSandbox server, exposes noVNC inspection URLs, connects over proxied CDP, and uploads WebM session recordings to object storage with the same deferred recording_url semantics as Steel. Pass storage to BrowserUseClient when recording is enabled.

DevTools note: the Chrome image exposes CDP on 0.0.0.0:9222 (--remote-debugging-address=0.0.0.0 plus a socat forward for Chromium M113+). Rebuild from examples/opensandbox/chrome after pulling changes; the SDK discovers CDP via sandbox.get_endpoint(9222). See examples/opensandbox/chrome/README.md.

OpenSandbox local setup:

DOCKER_HOST=unix://${HOME}/.docker/desktop/docker.sock \
  OPENSANDBOX_INSECURE_SERVER=YES opensandbox-server

cd libs/gl-browser-use/examples/opensandbox/chrome
docker build -t opensandbox/chrome:latest .
playwright install chromium

MinIOS3CompatibleStorage uploads session recordings to MinIO or an S3-compatible service and returns presigned URLs.

Development

From libs/gl-browser-use:

make install-dev
make test-unit
make test-integration
make lint
make build-check

Useful targets:

1. make test: run all tests.
2. make test-unit: run unit tests with coverage.
3. make test-integration: run integration-marked contract tests.
4. make lint: run Ruff checks.
5. make format: run Ruff fixes and formatter.
6. make pre-commit: run pre-commit hooks.
7. make build-check: build the package and validate artifacts with Twine.