> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lupin.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser sessions

> Search and read the web or operate isolated Cloudflare Browser Run sessions.

# 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:

```jsonc theme={null}
{
  "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.

```bash theme={null}
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
```

```ts theme={null}
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](https://developers.cloudflare.com/browser-run/reference/browser-binding-api/),
[Live View and URL expiry](https://developers.cloudflare.com/browser-run/features/live-view/),
and [session reuse](https://developers.cloudflare.com/browser-run/features/reuse-sessions/).

## 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.

```ts theme={null}
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](https://docs.lupin.sh/AGENT-TOOLS.md) for the complete catalog and messaging limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.