agent-browser

agent-browser is the browser runtime provider for the agent system.

It is responsible for real browser/session automation, not generic network protocol plumbing.

Backend decision

Initial real backend package: headless Chromium controlled with chromedp.

The executable now speaks the rpc-plugin-system substrate lifecycle contract and starts under agent-core-host. It defaults to the deterministic fake backend, and it can explicitly select the headless chromedp backend with AGENT_BROWSER_BACKEND=chromedp or -backend chromedp. Chromium discovery uses AGENT_BROWSER_CHROMIUM_EXECUTABLE / -chromium-executable first, then configured candidates from AGENT_BROWSER_CHROMIUM_CANDIDATES / -chromium-candidates, then known installed Chromium/Chrome paths; it never downloads or installs Chromium at runtime and fails closed when no executable is available.

Deployment assumes no desktop, no X11, and no Wayland. Chromium must run headless and is controlled through Chrome DevTools Protocol. Each agent runs under its own Unix user with separate runtime/profile state; this is a custom agent-system model, not an OpenClaw browser dependency. V1 also includes explicit attach-only existing-user-browser mode, gated by mediated profile/session authority rather than ambient profile possession.

rod and Playwright are not first-slice dependencies. Add another backend only if chromedp hits a concrete limitation.

Purpose

agent-browser owns browser-specific runtime behavior:

• browser process/profile lifecycle
• navigation
• DOM interaction
• JavaScript execution boundaries
• screenshots and visual capture
• form interaction
• downloads/uploads where admitted
• browser storage/session use through scoped leases
• browser automation audit events

The current executable is substrate-compatible. Fake remains the default smoke backend; chromedp is available as the explicit real headless backend.

Authority boundaries

agent-browser is not the action authority and not the credential authority.

• agent-core-system owns action admission, approval, policy, audit, and execution envelopes.
• rpc-plugin-system owns substrate runtime, transport, lifecycle, and plugin supervision.
• agent-keyring owns browser/session credentials, cookies, tokens, passkeys where applicable, scoped leases, refresh/renewal, revocation, and credential audit metadata.
• agent-network owns generic network protocol adapters such as HTTP, WebSocket, gRPC, TCP/TLS, and SSH-mediated network operations.
• agent-browser owns browser runtime semantics.

Credential possession is not action authorization. Browser-session access requires scoped credential/session leases from agent-keyring and admitted action envelopes from agent-core-system.

Non-goals

• Do not store credentials here.
• Do not become a general network client; use agent-network for protocol-level network operations.
• Do not bypass agent-core-system admission.
• Do not silently reuse browser sessions across unrelated sites/accounts/actions.
• Do not expose raw cookies/session tokens by default.
• Do not automate user-visible actions without explicit admitted scope.

First useful implementation slice

1. Define browser capability contracts.
2. Define session/profile lease requirements against agent-keyring.
3. Define audit/redaction rules.
4. Add a fake browser backend for tests.
5. Add a chromedp backend for headless Chromium.
6. Add attach-only existing-user-browser mode behind mediated profile/session authority.
7. Add a headless smoke test using a local static page before touching authenticated sessions.