Skip to main content

scalebrowser: the Python SDK

Official Python SDK for the Scalebrowser daemon: a typed REST client plus a direct-CDP driver (nodriver-style) for the self-hosted browser infrastructure that gives each AI agent its own browser.

The driver plane is direct-CDP, not Playwright/Puppeteer: anti-bot stacks block the Playwright control plane regardless of how good the browser patches are. start_profile returns a cdp_ws endpoint and this SDK speaks the Chrome DevTools Protocol over it directly. Credentials never leave the daemon and are never logged by the SDK.

Install

pip install scalebrowser

Requires Python ≥ 3.10 and depends on httpx, websockets, pydantic v2. The SDK is MIT-licensed; the daemon it talks to is a separate, licensed product.

Quickstart (sync)

from scalebrowser import ScalebrowserClient, CreateProfileBody

sb = ScalebrowserClient(base_url="http://127.0.0.1:8787", token="…")

profile = sb.create_profile(CreateProfileBody(name="acct-01"))

# start → direct-CDP connect → navigate → humanized click → stop
with sb.launch(profile.id, headless=True) as page:
    page.navigate("https://example.com")
    print(page.evaluate("document.title"))
    page.humanize_click(120, 240)        # routed through the daemon's humanized input

sb.close()

Quickstart (async)

import asyncio
from scalebrowser import AsyncScalebrowserClient

async def main():
    async with AsyncScalebrowserClient(token="…") as sb:
        started = await sb.start_profile(profile_id, headless=True)   # StartProfileResult
        async with await sb.connect_cdp(started, profile_id) as page:
            await page.navigate("https://example.com")
            title = await page.evaluate("document.title")
            await page.humanize_click(120, 240)
        await sb.stop_profile(profile_id)

asyncio.run(main())

REST surface

Every /v1 endpoint is a typed method on the client, under the same name in both the sync and the async client:

  • Profiles: list_profiles, list_profile_ids, count_profiles, get_profile, create_profile, update_profile, delete_profile, start_profile, stop_profile. release_profile drops an agent's lease without its handle (the operator's way out), and takeover_profile asks for a profile that is open on another machine of your account
  • Bulk: bulk_create_profiles, bulk_start, bulk_stop, bulk_delete, bulk_assign_proxy, bulk_assign_extensions
  • Groups / Presets: list_groups/create_group/get_group/update_group/delete_group, list_presets/create_preset/get_preset/update_preset/delete_preset, get_persona_constraints. A preset is config (what the profiles do: geo_mode, proxy_id, …) plus constraints (what they are: country, which pins the persona's language, timezone and voices). Both are typed (PresetConfig / PresetConstraints) and the daemon refuses an unknown key with a 400, so read the valid regions from get_persona_constraints() rather than hardcoding them.
  • Proxies: list_proxies/create_proxy/get_proxy/update_proxy/delete_proxy/check_proxy, plus check_proxy_config (probe a config before saving it; pass id to reuse an existing proxy's stored credentials)
  • Extensions: list_extensions, attach_extension, detach_extension, plus the daemon-wide library (list_library_extensions, upload_extension, get_library_extension, delete_library_extension, delete_library_extension_version). An attached package IS loaded into the browser at launch, under the canonical Web-Store id its own key derives
  • Credentials: list_credentials, put_credential, delete_credential, reveal_credential (needs the vault password), export_credentials, import_credentials. The vault password itself: vault_status, set_vault_password
  • Secret layer: get_secret_layer, set_secret_layer, list_secrets, update_secret, delete_secret. scrub_text filters a text you hold against a profile's values, and run_with_secrets runs a command with named values in its environment, so no value crosses a socket
  • Cookies: reveal_cookies, the one route a cookie VALUE leaves through, behind the same vault password
  • Recorded requests: reveal_request, the one route what a request carried (query, header values, body) leaves through, behind the same vault password
  • Sessions: export_session, import_session
  • Mailboxes: list_inboxes, create_inbox, update_inbox, delete_inbox, get_inbox_bindings, bind_inbox, unbind_inbox, which is where a profile's confirmation codes arrive. reveal_inbox reads them: every message, the code candidates in it and each link with its full address, behind the vault password because a sign-in link IS the account
  • Passkeys: list_passkeys, delete_passkey. Metadata only: the private key has no field and no endpoint
  • Agent runs: list_runs, get_run, list_run_steps, get_run_shot, get_activity. Read-only, all of it
  • Interruptions: list_interruption_locks, set_interruption_lock, list_interruption_rules, set_interruption_rule, delete_interruption_rule: who may answer when the browser asks something. list_pending_interruptions shows what waits in a tab right now and respond_interruption answers it; a kind an operator lock decides is refused (409)
  • Artifacts: put_artifact (hand the daemon a file to upload later), get_artifact (fetch a screenshot, download or saved PDF as bytes)
  • Tasks and memory: list_tasks, create_tasks, cancel_task, delete_task, plus a profile's standing instructions for agents, its PROFILE.md: get_profile_memory, put_profile_memory, delete_profile_memory
  • Videos: list_videos, get_video, rename_video, delete_video, cancel_video, rerender_video, video_access, download_video_file, videos_storage; recordings with list_recordings, get_recording, delete_recording_raw, render_recording; public links with share_video, share_status, revoke_share
  • Video presets: list_video_presets, get_video_preset, create_video_preset, update_video_preset, duplicate_video_preset, delete_video_preset, and a look at an unsaved config with preview_video_preset, preview_video_preset_clip, download_video_preset_clip. The files a preset points at: list_media, upload_media, delete_media, media_file. Narration keys: list_tts_providers, put_tts_provider, verify_tts_provider, delete_tts_provider. Encoders: get_codecs, set_codec_enabled
  • Fingerprint audit: start_audit drives the profile's running browser through the external detector pages, get_audit reads the state and the last report
  • Exit addresses: get_exit_status (which addresses a profile owns), and the machine's rule that one address belongs to one profile: get_exit_rule, set_exit_rule
  • Machine settings: get_remote_access, set_remote_access (may a chat service reach this machine's browsers), get_agent_tools, set_agent_tool_group (which optional MCP tool groups agents see), get_connection (which installation answered: its data directory and its binary)
  • Workflows: list_workflows, get_workflow, create_workflow, edit_workflow, rename_workflow, delete_workflow, workflow_delete_preview, extract_workflow. extract_workflow moves a part of the draft into a workflow of its own
  • Workflow versions: list_workflow_versions, get_workflow_version, save_workflow_version, publish_workflow, diff_workflow, revert_workflow, adopt_workflow_version, undo_workflow_batch. Saving, publishing and going back
  • Workflow runs: start_workflow_run, list_workflow_runs, get_workflow_run, list_workflow_run_steps, list_workflow_run_files, get_workflow_run_file, cancel_workflow_run, fork_workflow_run, preview_workflow_run_fork, decide_workflow_run, workflow_queue, workflow_usage, get_workflow_readiness. A fork runs again from a chosen step and keeps the outputs before it
  • Approvals: list_workflow_approvals, decide_workflow_approval, get_approval_webhook, set_approval_webhook. Steps that wait for a person
  • Triggers and switches: workflow_hooks, rotate_workflow_hook, list_workflow_fires, list_workflow_switches, set_workflow_switch, emergency_stop_workflows. Schedules and webhooks need a paid plan (4014 on Free)
  • Variables and files: list_workflow_variables, set_workflow_variable, reveal_workflow_variable, get_workflow_file_access, set_workflow_file_access, grant_workflow_folder, ungrant_workflow_folder, list_workflow_fast_domains, put_workflow_fast_domain, delete_workflow_fast_domain. A secret variable is shown again only through reveal_workflow_variable, behind the vault password
  • Repairs: list_workflow_repairs, get_workflow_repair, revert_workflow_repair, get_workflow_repair_metrics. The fixes the repair made when a step broke
  • Building blocks: list_node_types, get_node_type, get_workflow_settings_schema, get_workflow_reference_sources, workflow_templates, instantiate_template
  • Sharing and machines: share_workflow, import_shared_workflow, revoke_workflow_share, workflow_machines, cancel_workflow_forward. workflow_machines names the machine each profile lives on; a start sent there can be cancelled
  • Tables: count_table_rows, create_table, delete_table, edit_table, export_table, get_table, import_table, list_table_rows, list_table_trash, list_tables, restore_tables, update_table. The data a workflow reads and writes, with a trash
  • Google Sheets: connect_google, disconnect_google, link_sheet, list_google_connections. Linked with Google's own picker; on Free only through your own Google Cloud project
  • Model sources: check_ai_source, create_ai_source, delete_ai_source, get_ai_settings, list_ai_invocations, list_ai_sources, put_ai_settings, update_ai_source. The keys and models behind the AI steps
  • White label: agency_clients, set_agency_ai_key, set_agency_distribution, set_client_brief_mode, set_wl_sharing, wl_sharing. For an Enterprise agency and its clients
  • Input / Metrics / Account / Events: send_input, get_metrics, get_account, health, ready, events(). Close the client with close() (sync) or aclose() (async), or use it as a context manager
async for event in sb_async.events():        # SSE lifecycle stream (Bearer-authenticated)
    print(event.type)                          # typed: profile_started / profile_crashed / …

Errors map the daemon contract: ApiError(status, code, message) with codes 4001–4014 (4014 is a plan limit, with plan_limit in its body; ApiError.is_auth_error for 401 / 4010); NetworkError when the daemon is unreachable; CdpError for protocol-level failures.

Direct-CDP driver

CdpSession (async) / SyncCdpSession give you:

  • send(method, params): any CDP command, awaited by id
  • navigate(url), evaluate(expr, isolated=False), which never call Runtime.enable (a detection leak); isolated worlds via create_isolated_world(). The wait for the load reads from an isolated world, so a page that watches its own document.readyState sees no foreign read
  • on(method, cb) / events(): subscribe to CDP events
  • humanize_move/click/type/scroll: humanized OS-level input via the daemon

Tests

pip install -e ".[dev]"
pytest                       # unit tests (mock REST + a real fake-CDP ws server)
SCALEBROWSER_E2E=1 pytest tests/test_e2e.py   # against a real daemon

Contract assumptions

  • Default base URL http://127.0.0.1:8787; Bearer token always.
  • The CDP endpoint is guarded by the OS user, not by that token. The engine's DevTools port has no authentication of its own: it answers a bogus bearer with 200, measured, so the engine drops any connection whose peer process runs as a different user. Nothing to configure and nothing to pass: your process is the one that started the profile, so it is on the allowed side. A helper running as another account will not get in, by design.
  • The trusted-input body beyond {action, humanize} (coordinates, button, delta_x/y, text) is an SDK convention; see cdp.py.
  • Two endpoints are optional and answer 404 on a daemon without them, which the SDK treats as information rather than as an error: get_metrics() then derives running counts from profile state, and get_account() returns licensed=False, which is what "self-hosted, no control plane" means.
  • Every method is present on BOTH clients under the same name. The sync client is a hand-written mirror over one background event loop; there is no duplicated endpoint logic.

Metadata

Release files for scalebrowser 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for scalebrowser 1.3.0
File Size Uploaded Provenance Actions
scalebrowser-1.3.0.tar.gz 105.1 kB With provenance Details for scalebrowser-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for scalebrowser 1.3.0
File Interpreter ABI Platform Actions
scalebrowser-1.3.0-py3-none-any.whl Python 3 none any Details for scalebrowser-1.3.0-py3-none-any.whl

Total release size: 243.5 kB

Release files / scalebrowser-1.3.0.tar.gz

Download URL scalebrowser-1.3.0.tar.gz
Size 105.1 kB
Tags Source
SHA-256 checksum
How to use checksums
80d9b31aeaf6cd05df2a75808486df0344b42e4e4fa6576a62d97fc365547761
BLAKE2b-256 checksum
How to use checksums
b88ea6e08154b1766f3b9264ffb1967b4d11c0a93b8672bffd4329dc5293c289
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / scalebrowser-1.3.0-py3-none-any.whl

Download URL scalebrowser-1.3.0-py3-none-any.whl
Size 138.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a56f4d0c38cf0102d18ba50e0b5286ca006e356c17fce18d7d8127932c606f9d
BLAKE2b-256 checksum
How to use checksums
57adfe052fe3900101190d87703e74225a1589f0de2147266f9d31c6053cb172
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for scalebrowser 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for scalebrowser-1.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page