surfari

What it does

Surfari gives agents a stable browser surface. The caller asks Surfari to browse; Surfari checks the available providers, picks the best backend for the task, runs it, and records proof above the backend.

Right now the default provider is agent-browser through the Eidos ab wrapper. Browserbase handles remote sessions when configured. The learning layer lives above every backend, so playbooks and proof survive provider churn.

Install

The PyPI name surfari is already occupied by another project, so install the Eidos build from GitHub for now.

uvx --from git+https://github.com/eidos-agi/surfari.git surfari --help
pip install git+https://github.com/eidos-agi/surfari.git
pip install 'eidos-surfari[browserbase] @ git+https://github.com/eidos-agi/surfari.git'

Check the browser stack

surfari doctor
surfari browse status --json
surfari browse open https://example.com
surfari browse snapshot
surfari browse open --remote --keep-alive https://example.com
surfari browser status --json
surfari browserbase status --json

Use --provider auto|agent-browser|browserbase only when proof or debugging needs a pinned backend. Otherwise leave provider selection to Surfari.

On the Mac mini, Surfari currently auto-selects the Eidos agent-browser wrapper:

SURFARI_HEADED=0 surfari browse open --session surfari-headless https://example.com
SURFARI_HEADED=1 surfari browse snapshot --session surfari-headed

Browserbase remote mode

Browserbase support is optional and stays behind the browserbase extra. Surfari reads only these environment names and reports their values as present or missing:

BROWSERBASE_API_KEY
BROWSERBASE_PROJECT_ID
SURFARI_BROWSERBASE_TIMEOUT
SURFARI_BROWSERBASE_KEEP_ALIVE

Use keep-alive only when a later command needs to reconnect to the same remote session, then release it explicitly. Normal callers can stay on surfari browse; surfari browserbase remains available for provider-specific debugging.

surfari browse open --remote --keep-alive https://example.com
surfari browse snapshot --provider browserbase
surfari browse screenshot --provider browserbase --out evidence/browserbase-smoke.png
surfari browse release --provider browserbase

Use it for

• Browser readiness — prove what is installed before an agent starts.
• Provider selection — abstract away which browser automation backend is best this month.
• Site playbooks — keep repeated web workflows file-backed and reviewable.
• Cheap surfing — use deterministic browser primitives before expensive model calls.
• Headed and headless checks — switch with SURFARI_HEADED.
• Remote browser control — run Browserbase sessions without publishing credentials or private artifacts.

Case study status

A token-savings case study is in preparation. Private evidence shows multi-million-token cached browser sessions, but the public savings claim will ship only after the baseline and comparison model are explicit. This page intentionally avoids unsupported savings claims and raw private evidence.

Safety boundary

Surfari should stop for human approval before sending messages, uploading files, submitting forms, changing settings, paying, purchasing, deleting, filing, or using credentials and MFA. Browser profiles, cookies, authenticated screenshots, and private page text do not belong in public evidence.