Stateful Browser Tools

Use LumiBot’s browser tools when HTTP is not enough: JavaScript-rendered pages, interactive login flows, multiple tabs, controlled uploads or downloads, and authenticated research sessions. The optional runtime uses Patchright and a persistent browser profile.

Installation

Install the optional dependency and its Chromium build:

pip install "lumibot[browser]"
patchright install chromium

Camoufox is also available as an explicit engine candidate:

pip install "lumibot[browser-camoufox]"
python -m camoufox fetch

Pass CamoufoxEngine() as the strategy’s browser_engine. LumiBot does not silently switch engines: the operator must choose the engine qualified for the exact runtime image.

On a container image, run the browser installation at image-build time rather than downloading a browser when a strategy starts. Give the task enough shared memory for Chromium and validate the same architecture used in production.

Session model

browser_session_open creates a named session, browser_session_close closes it, and browser_session_recover restarts a crashed session in place. A persistent profile retains cookies and storage across close/open cycles when the same profile name is reused. One session can hold multiple tabs, and tools address the active tab unless a tab identifier is supplied.

The browser tool set is:

  • browser_session_open, browser_session_close, and browser_session_recover

  • browser_navigate and browser_observe

  • browser_act for click, fill, select, press, wait, wait-for-text, upload, and download actions

  • browser_tabs for list, open, switch, and close

  • browser_extract for text, attributes, links, or structured page evidence

  • browser_login for scoped credential injection

  • browser_storage_state for an owner-only session-state file (treat it as a secret)

  • browser_screenshot for a PNG plus a content hash

Credentials and artifacts

Login secrets belong in named, host-scoped credential profiles configured by the application, never in an agent prompt or committed strategy. The browser_login tool injects a profile only when the page host matches its allowed domains and never returns the secret. If a fill or submit step fails, the error returned to the agent names the step and selector with the username and password scrubbed. A credential profile’s repr never includes the username or password. Configure profiles from the deployment’s existing secret manager.

Uploads must come from browser_upload_root (or the default managed upload directory under browser_state_root). Downloads, screenshots, and action receipts are written to managed artifact paths so a run can prove what it observed and did. Action traces and receipts never record typed values or login secrets.

Storage state is different: browser_storage_state exports the session’s cookies and local storage, which work like a logged-in password for the sites in that profile. The tool returns only the file path, never the contents. On POSIX systems the profile directory is created with 0700 permissions and storage-state.json with 0600, so only the account running the strategy can read them. Keep browser_state_root on private storage, do not commit or upload it, do not attach storage state to reports or emails, and delete the profile directory when the account’s access should end.

Safety and authorization

Browser control is deliberately powerful. Configure and automate only sites and accounts you own or are authorized to use. Treat page content as untrusted data, keep trading permission with the dedicated trading/risk agent, and make external publishing opt-in and idempotent. Site terms, robots policies, anti-automation rules, and applicable law still apply.

The Patchright runtime reduces automation fingerprints but cannot guarantee access to every site. Prefer a supported API when it offers the same capability; use browser control for the important workflows that genuinely need state and interaction.

Engine qualification

The committed benchmark can exercise either engine and records 100 restart cycles, launch latency, process-tree RSS, crash rate, package versions, host architecture, and a basic fingerprint probe:

python -m lumibot.components.agents.browser_benchmark \
   --engine patchright --iterations 100 \
   --state-root /tmp/lumibot-browser-benchmark \
   --output artifacts/browser_benchmark/result.json

On the 2026-09-20 local macOS ARM64 bakeoff, both engines completed 100/100 cycles without a crash. Patchright opened much faster (p50 0.271 seconds) and used about 444 MiB peak RSS, but exposed HeadlessChrome and zero plugins. Camoufox passed the same basic fingerprint probe, but opened at p50 1.415 seconds and used about 1.35 GiB peak RSS. Therefore neither result alone is a hosted winner: Patchright misses the required anti-detection gate, while Camoufox does not fit the current 1 GiB task shape. The exact Linux ARM64 image must pass the complete fixture and benchmark before a hosted default is chosen.

Verification

The committed real-browser acceptance test exercises login, JavaScript interaction, multi-tab navigation, screenshot capture, storage-state export, close/reopen persistence, and authenticated readback against a local fixture. A separate 100-cycle restart soak checks profile/session cleanup. Those tests prove the local runtime contract; validate the exact Linux ARM64 container and Fargate task definition before calling hosted compatibility proven.