Browser Concepts

A browser sandbox is a Firecracker microVM running a stealth browser daemon. You pick an engine rather than a compute template, then drive the browser over CDP (Playwright/Puppeteer) or the NDJSON /rpc action API. One sandbox is exactly one browser session.

Engines

Two public engines, selected by the browser field at create time:

The public engine names deliberately hide the underlying stealth implementation. Power users can override the backing template with templateID for a custom uni-browser variant.

Contexts

A context is an isolated browsing context on a running sandbox - its own cookies and storage, optionally with its own BYO proxy. Creating a context does not restart the browser, so it works on a warm browser.

A proxy attached to a context is immutable for that context's life. To use a different proxy, create a new context (or a new sandbox). See contexts.* in the SDK reference and the /browser-sandboxes/{sandboxID}/contexts endpoints in the API reference.

Artifacts

An artifact is a screenshot, PDF, trace, video, or HAR file captured from a browser session and persisted server-side. Two facts shape how you use them:

1. The server stores client-captured bytes - it does not capture for you. You capture the artifact yourself (via CDP / Playwright) and upload the base64 bytes to POST /browser-sandboxes/{sandboxID}/artifacts. The SDK's bound artifacts.screenshot() / artifacts.pdf() helpers do the capture-then-upload for you.

2. Download is a separate route. Each persisted artifact record carries a downloadURL. That URL points at a dedicated download route that is served outside the OpenAPI surface:

   GET /browser-sandboxes/{sandboxID}/artifacts/{artifactID}

   Fetch it with your normal auth headers (X-API-Key / bearer). The handler re-checks browser-flavor access, then streams the bytes from the artifact store. Downloads are always served as an attachment with X-Content-Type-Options: nosniff (a stored-XSS defense), so an artifact never renders inline.

pdf() is chromium only - Playwright's page.pdf() is unavailable on Firefox.

Replay events

Each browser sandbox keeps a discrete replay-event log - a timeline of lifecycle, connection, navigation, artifact, and preview breadcrumbs, queryable via GET /browser-sandboxes/{sandboxID}/replay-events (newest first). It survives control-plane restarts.

Suspend / resume vs. "no durable pause/recover"

There are two statements that look contradictory but are not:

• Browser sandboxes do not support durable pause/recover.
• The REST API exposes POST …/suspend and POST …/resume.

Both are true. The suspend/resume endpoints today perform a vCPU freeze (an in-RAM pause), the same behavior as a regular sandbox pause - they do not take a durable snapshot that survives the node. A browser session carries live, time-sensitive state and fingerprints, so durable snapshot/restore is not a supported primitive for it.

The right way to keep working with a browser sandbox is to stay connected, or to reconnect to a still-running sandbox with lel.browser.connect(sandboxId) (the access token is returned on GET for a running or paused sandbox so a client that lost it - a reload, a new tab, an agent failover - can reattach). Treat the lifecycle as create → use → close, not pause-and-come-back-later.

See also

• Browser SDK - the lel.browser.* surface.
• CDP Wire Contract / RPC Wire Contract - the raw protocols.
• Browser Sandboxes API reference - the REST endpoints.