BAP sessions keep browser state alive across commands. When a client disconnects, the server parks the browser pages and contexts instead of destroying them. On reconnect with the same session ID, state is restored instantly.
How Sessions Work
bap -s=research goto https://example.com
↓ connects with sessionId: "research"
BAP Server creates browser + page
↓ client disconnects
Server parks session (browser, pages, contexts, element registries)
↓ 30 seconds later...
bap -s=research observe
↓ reconnects with sessionId: "research"
Server restores parked session → page is still on example.com
Named Sessions
Use the -s flag to create and reuse named sessions:
# Start a research session
bap -s=research goto https://arxiv.org --observe
# Start a shopping session (separate browser context)
bap -s=shopping goto https://store.example.com --observe
# Come back to the research session later
bap -s=research click text:"Next paper"
# List all active sessions
bap sessions
Without -s, the CLI auto-generates a session ID as cli-<port> (e.g., cli-9222). This means even without explicit naming, your session persists across commands on the same port.
Dormant Session Lifecycle
Park
When a client disconnects, the server parks the session. All state is preserved: browser instance, browser contexts, open pages, page-to-context mappings, element registries, frame contexts, and session approvals.The server also snapshots context.storageState() for crash recovery (best-effort, non-blocking).
TTL countdown
A dormant session has a configurable TTL (default: 300 seconds / 5 minutes). If no client
reconnects within the TTL, the session expires and all resources are cleaned up.
Restore
When a client connects with a matching sessionId, the server checks if the parked browser is
still alive. If so, all state is transferred to the new client connection. If the browser crashed
during dormancy, the server starts fresh.
Expire
After TTL, dormant sessions are destroyed. Owned browsers are closed. CDP-attached (borrowed) browsers have their reference dropped without closing the external browser process.
What Gets Preserved
| State | Preserved? | Notes |
|---|
| Browser instance | Yes | Stays running during dormancy |
| Open pages and URLs | Yes | Including scroll position and form state |
| Browser contexts | Yes | Including cookies and localStorage |
| Element registries | Yes | Stable refs remain valid |
| Frame contexts | Yes | iframe state preserved |
| Session approvals | Yes | Previously approved actions stay approved |
| Storage state snapshot | Yes | Best-effort crash recovery backup |
Ghost Page Filtering
When a dormant session is restored, some pages may come back as about:blank if the browser discarded them during dormancy. BAP filters these out automatically — any page with url === "about:blank" is treated as non-existent, and ensureReady() creates a fresh page.
Without this filter, commands after session restore would silently operate on a blank page. BAP
handles this transparently.
MCP vs CLI Sessions
| Behavior | CLI | MCP |
|---|
| Session persistence | Yes (auto sessionId) | No (destroy on disconnect) |
| Default session ID | cli-<port> | None |
| Named sessions | -s=<name> | Not supported |
Configuration
The dormant session TTL is configured on the server:
| Option | Default | Description |
|---|
dormantSessionTtl | 300s | Time before a parked session is destroyed |
session.maxDuration | 3600s | Maximum total session duration |
session.idleTimeout | 600s | Idle timeout before server-side disconnect |
Practical Patterns
Multi-task agent
# Agent works on task A
bap -s=task-a goto https://site-a.com
bap -s=task-a observe
bap -s=task-a act click:text:"Download"
# Switch to task B without losing task A
bap -s=task-b goto https://site-b.com
bap -s=task-b extract --fields="title,status"
# Resume task A -- page is exactly where we left it
bap -s=task-a screenshot
Long-running workflow with breaks
# Start a multi-step workflow
bap -s=onboarding goto https://app.example.com/signup --observe
bap -s=onboarding act fill:label:"Email"="user@test.com" click:role:button:"Next"
# Agent pauses to process other tasks (session stays warm for 5 minutes)
# ...
# Resume where we left off
bap -s=onboarding observe
bap -s=onboarding act fill:label:"Company"="Acme Inc" click:role:button:"Continue"
