A browser session lifecycle an agent can reason about

One session is one temporary workspace

A Lupin browser session is an isolated Cloudflare Browser Run browser registered to your organization. The registry gives you a durable resource identity, while the actual browser remains temporary. Start by deciding what evidence the task must produce and which state must survive outside the browser. A page URL, selected facts and an explicit completion record are useful outputs. Cookies and signed-in pages are session state: Lupin does not persist a profile after the session closes. A session name helps people recognize work; it is not an authentication boundary or a reusable profile identifier.

Check readiness before allocation

Use the capabilities endpoint before asking the agent to create anything. Browser availability depends on the deployed BROWSER binding, durable storage, workspace permissions, billing eligibility and provider capacity. A bootstrap registration key is limited to reading, email and drafts; successful registration does not authorize a paid browser. An organization key needs api_key_create to allocate and request access links, api_key_read to inspect, and api_key_delete to end the session. Project-scoped and inbox-scoped keys cannot manage shared browser sessions. Resolve missing prerequisites with the human owner before spending effort on page instructions.

Keep the resource identity stable

Create a lowercase session name with letters, digits and dashes, up to 63 characters, and preserve one Idempotency-Key for that allocation. Store the returned session_id in your task record. If the response is lost, retry the same request with the same key instead of requesting another browser. A changed name or runtime under the original key can conflict. After creation, list sessions to inspect lifecycle metadata. Access URLs are deliberately absent from lists; obtain them only through the explicit connect action when an operator or CDP client needs a connection.

curl -X POST https://api.lupin.sh/v0/browsers/sessions \
  -H "Authorization: Bearer $LUPIN_API_KEY" \
  -H "Idempotency-Key: research-task-001" \
  -H "Content-Type: application/json" \
  -d '{"name":"research-task","timeout_seconds":60}'

Separate access expiry from runtime

The connect response contains live_view_url, connect_url and access_expires_at. Its five-minute deadline governs starting a connection; it does not promise five minutes of browser runtime or end an established connection at that instant. The browser also has inactivity behavior and, in billing-enforced workspaces, a finite runtime lease. Lupin requests at most a ten-minute inactivity timeout, shortened when the lease requires it. Read the returned metadata and your workspace runtime policy instead of assuming an hour of execution. Refresh an expired access link for the same active session rather than allocating another browser.

Finish with confirmed closure

Place the end call in the task's cleanup path, including when navigation or extraction fails. Save useful output before ending, then inspect the result and session lifecycle record. A provider failure is not proof of successful cleanup. If an operation reports an uncertain allocation or closure, keep the known session identity and investigate that resource before creating a replacement. An ended browser requires a new session; reopening an old link cannot recover its cookies. This design makes cleanup a deliberate workflow transition and leaves an auditable record of what the agent attempted, observed and completed.

Sources & verification

Reviewed against the current Lupin route, provider adapter and shared input contracts, plus the linked official references. Examples were not run against live services.

• developers.cloudflare.com · browser-run · reference · browser-binding-api ↗Checked 2026-11-05
• developers.cloudflare.com · browser-run · features · reuse-sessions ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.