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

# Sessions

> Persistent browser sessions that survive across CLI invocations

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:

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

<Tip>
  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.
</Tip>

## Dormant Session Lifecycle

<Steps>
  <Step title="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).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Warning>
  Without this filter, commands after session restore would silently operate on a blank page. BAP
  handles this transparently.
</Warning>

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

MCP clients get the current destroy-on-disconnect behavior. Session persistence is a CLI-specific feature designed for agents that make multiple sequential shell commands.

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

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

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