Session Management
Browserless gives you two ways to keep state — cookies, localStorage, cache, authentication — across browser connections. Which one to use depends on how long you need to keep the browser alive and if you know you need to persist this beforehand or during runtime of your script.
How Session Persistence Works
When a Puppeteer script (or any other library) connects to Browserless, it gets a remote browser process. By default, that process is closed the moment your connection drops. Session persistence changes that behavior.
Standard Sessions
Call the CDP command Browserless.reconnect mid-script to flag the browser as reconnectable. The server holds the browser process open for a configurable timeout window. Reconnecting within that window drops you back into the live browser exactly where you left it: same page, same scroll position, same in-memory state. The browser is cleaned up once the TTL expires or you close it.
Persisting State
The Session API lets you create browser sessions via REST — returning a set of URLs and a WebSocket endpoint you use to connect and manage the session lifecycle. The session gets its own persistent directory on disk for cookies, localStorage, and cache. The browser process itself can be stopped and restarted freely — data survives because it's written to disk. You can also set processKeepAlive to hold the browser process open between connections, restoring full live state on reconnect. Sessions stay alive for days, up to the maximum allowed by your plan.
Under the hood, each session is backed by an isolated userDataDir — the same Chrome mechanism used for user profiles. Browserless provisions and scopes these directories per-session, ensuring data isolation across connections on shared fleets.
Choosing an Approach
| Standard Sessions | Persisting State | |
|---|---|---|
| How you set it up | CDP command called mid-script | REST API call before connecting |
| State survives | While browser process is running (up to 5 min timeout) | For days, across full browser restarts |
| Keep browser process alive | Built-in, up to 5 min | Optional via processKeepAlive |
| Library support | Puppeteer only (requires browser.disconnect()) | Puppeteer, Playwright, or any other library |
| Session lifetime | Short — seconds to a few minutes | Long — hours to days |
| Control | Decide mid-execution whether to persist | Define lifecycle upfront with explicit TTL |
| Management | No separate create/delete step | Create and delete via HTTP |
Use Standard Sessions when:
- You're already in a running Puppeteer script and want to conditionally keep the browser alive mid-execution.
- Your disconnection window is short — you'll reconnect within seconds or a few minutes.
- You don't need state to outlast the browser process.
Use Persisting State when:
- You need cookies, localStorage, or auth state to survive for hours or days.
- You want to create, manage, and terminate sessions through a REST API.
- You need to predefine session configuration (TTL, stealth mode, proxy) before a browser connects.
- You're using Playwright or another library — Playwright lacks
browser.disconnect(), making Standard Sessions unreliable. - You want to keep the browser process alive between connections using
processKeepAlive. See Keeping Browser Sessions Alive.