Browser sessions

Lupin uses Cloudflare Browser Run to create isolated browser sessions with a durable, organization-owned registry. It is separate from the Boat container API. Check /v0/capabilities for the connected workspace’s provider availability. Autonomous unverified workspaces cannot start paid sessions.

Operator prerequisites

Apply API migrations (including the product registry), bind D1, and add a native Cloudflare browser binding named BROWSER to the API Worker:

{
  "browser": { "binding": "BROWSER" }
}

The binding belongs to the Worker’s Cloudflare account. No Browserbase project, Browserbase API key or client-side Cloudflare token is needed. The account must have Browser Run access and sufficient session capacity. A missing binding returns 501 browsers_not_configured. Before activation, validate create, live view, CDP connection and end against the deployed Worker, then confirm the closed session. Organization keys require api_key_read for listing, api_key_create for creation/access links, and api_key_delete for ending a session. Project/inbox-scoped keys cannot manage shared workspace sessions.

lupin capabilities
lupin browsers create --name research
lupin browsers list
lupin browsers connect --session-id SESSION_ID
# Open live_view_url, or connect a CDP client to connect_url before access_expires_at.
lupin browsers end --session-id SESSION_ID

const session = await lupin.browsers.create({ name: "research" });
const access = await lupin.browsers.connect(session.session_id);
// Treat both URLs as credentials; do not log them.
// Start the connection before access.access_expires_at.
// Open access.live_view_url, or give access.connect_url to your CDP client.
await lupin.browsers.end(session.session_id);

Session lifetime and access

Names contain lowercase letters, numbers and dashes (up to 63 characters). Lupin requests a 600,000 ms (10-minute) inactivity timeout, exposed as idle_timeout_ms. This is not a fixed one-hour runtime. Cookies and sign-ins stay in the current session until it closes; Lupin does not yet persist profiles between sessions. Session recording is disabled. Custom Lupin proxy routing is not supported. List responses include sanitized lifecycle metadata. Only the explicit connect action returns access URLs. live_view_url opens Cloudflare’s hosted live view; connect_url is a Lupin URL restricted to that session for a CDP WebSocket client. Access links expire after five minutes, indicated by access_expires_at. This deadline applies to starting a connection, not the duration of an established connection. Request new links if they expire; this does not create a new session. The console removes expired Take over links and offers Refresh live view. Treat access URLs as credentials and avoid shared logs. End the session when work is complete. session_ended means the browser has closed and requires a new session. End requests close the provider session and record a durable end time. Provider failures return an error rather than claiming success. If creation succeeds but the registry write fails, the API attempts to close the browser; operators should inspect the Browser Run dashboard after an interrupted or failed request. Usage depends on Cloudflare session limits and account configuration. Local mocked tests do not demonstrate live provider availability. Provider references: browser binding API, Live View and URL expiry, and session reuse.

Page operations and research

POST /v0/browsers/sessions/:session_id/actions accepts a fixed action: tabs, read, navigate, new_tab, close_tab, click, fill, select, press, scroll, back, forward, reload or screenshot. Pass tab_id to select a specific page; otherwise the first page is used. Navigation takes a public url; click/fill/select take an exact visible selector. Fill takes text, select value, press key, and scroll direction with optional pixels. Mutations require api_key_create and a stable Idempotency-Key; reads require api_key_read. The session must belong to the caller’s workspace and have an active runtime lease. Unknown outcomes are never replayed. Page results include source URL, visible text, links, form controls and retrieval time. Screenshots return JPEG image_base64. Downloads and arbitrary code execution are disabled. POST /v0/browsers/research accepts { "action": "search", "query": "…" } or { "action": "read", "url": "https://example.com" }, with a stable Idempotency-Key. It creates a bounded, metered temporary session and closes it afterward. Search uses the configured Composio no-auth provider for result URLs, then Cloudflare for source reading. It consumes one app action plus browser runtime; explicit page reading consumes browser runtime only. Source pages and snippets are returned separately. Research needs creation and deletion permissions.

const page = await lupin.browsers.action(session.session_id,
  { action: "navigate", url: "https://example.com" }, crypto.randomUUID());
const research = await lupin.browsers.search("Cloudflare Browser Run", crypto.randomUUID());

Requested public research runs within the existing workspace permissions and spending limits. Browser creation, navigation and interactions retain human confirmation. MCP exposes the same catalog and returns screenshots as native image content. See Agent tools for the complete catalog and messaging limits.

Start

Email

Realtime

Phone and compute

Network

Platform

Build

Roadmap

Browser sessions

Browser sessions

Operator prerequisites

Session lifetime and access

Page operations and research

​Browser sessions

​Operator prerequisites

​Session lifetime and access

​Page operations and research

Browser sessions

Operator prerequisites

Session lifetime and access

Page operations and research