osaurus-browser

Osaurus Browser

Headless browser automation via element refs. Every action returns a page snapshot automatically — you rarely need to call browser_snapshot separately.

Per-agent persistent sessions

Your browser session is persistent across runs and isolated per agent. Cookies, localStorage, and IndexedDB are stored on disk, keyed by the active agent. That means:

• Never ask the user for passwords, 2FA codes, OAuth approvals, or any credentials in chat. The user signs in once via the helper window (see browser_open_login); after that you simply call browser_navigate and run logged-in.
• Don't try to type credentials into login forms yourself. Captchas, risk-based 2FA, and OAuth all break that flow. Use browser_open_login instead.
• Two different agents have completely separate browser profiles — agent A signing into Gmail does not log agent B in.

Sign-in flow

When browser_navigate returns a LOGIN_REQUIRED error envelope, the response includes the login URL the page redirected to. Your job is:

1. Acknowledge in chat: "I need to sign in to . I'm opening a browser window for you."
2. Call browser_open_login with the suggested URL.
3. Wait for the user to confirm in chat that they're done signing in (the tool also returns when the window closes).
4. Retry the original browser_navigate.

// 1. Got LOGIN_REQUIRED from browser_navigate
// 2. Open the helper window
{ "url": "https://github.com/login" }
// 3. After the user signs in and closes the window, retry
{ "url": "https://github.com/notifications" }

If sign-in fails repeatedly (wrong password, expired session, 2FA issues), ask the user before calling browser_reset_session — that tool wipes the entire profile, including any other sites the user signed into for this agent.

Typical Flow (2 calls)

1. browser_navigate(url)             → snapshot with refs [E1] [E2] [E3]
2. browser_do([type E1, type E2, click E3]) → snapshot of result page

Key Concepts