> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-interact-zdr-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Browser Sandbox > A secure browser sandbox where agents can interact with the web. For agent workflows, use [Interact](/features/interact). Interact is the supported CLI/MCP path and can be driven with prompts or code after a scrape; MCP also supports opening from a URL directly. | Surface | Use it for | Entry point | Agent surface | | - | - | - | - | | Browser Sandbox | Standalone browser sessions for API/SDK users that need a sandbox, CDP URL, live view, or persistent session lifecycle | `POST /v2/interact` | API and SDKs; hidden CLI browser command is legacy | | Interact | Acting on a scraped page; MCP can also open from a URL with `firecrawl_interact` URL mode | `POST /v2/scrape/{scrapeId}/interact`, CLI `interact` after scrape, or MCP `firecrawl_interact` | Recommended for CLI/MCP agent workflows | Firecrawl Browser Sandbox gives API and SDK users a secure browser environment where agents can interact with the web. Fill out forms, click buttons, authenticate, and more. No local setup, no Chromium installs, no driver compatibility issues. Agent browser and playwright are pre-installed. Available via [API](/api-reference/endpoint/browser-create), [Node SDK](/sdks/node#browser), [Python SDK](/sdks/python#browser), and [Vercel AI SDK](/developer-guides/llm-sdks-and-frameworks/vercel-ai-sdk). The hidden `firecrawl browser` CLI command is legacy; CLI and MCP agent flows should use scrape + interact instead. To add Interact support to an AI coding agent (Claude Code, Codex, Open Code, Cursor, etc.), install the Firecrawl skill: ```bash theme={null} npx -y firecrawl-cli@latest init --all --browser ``` Each session runs in an isolated, disposable or persistent sandbox that scales without managing infrastructure. ## Quick Start Create a session, execute code, and close it: * **No Driver Installation** - No Chromium binary, no `playwright install`, no driver compatibility issues * **Python, JavaScript & Bash** - Send code via API, CLI, or SDK and get results back. All three languages run remotely in the sandbox * **agent-browser** - Pre-installed CLI with 60+ commands. AI agents write simple bash commands instead of Playwright code * **Playwright loaded** - Playwright comes pre-installed in the sandbox. Agents can write Playwright code if they prefer. * **CDP Access** - Connect your own Playwright instance over WebSocket when you need full control * **Live View** - Watch sessions in real time via embeddable stream URL * **Interactive Live View** - Let users interact with the browser directly through an embeddable interactive stream ## Launch a Session Returns a session ID, CDP URL, and live view URL. ## Execute Code Run Python, JavaScript, or bash code in your session. Output is returned via `stdout`; for Node.js, the last expression value is also available in `result`. ### Handling File Downloads Files downloaded inside a session can be captured and returned as base64. Use Playwright's download API via the execute endpoint: ```python Python theme={null} import base64 async with page.expect_download() as download_info: await page.click('a#download-link') # Click the element that triggers the download download = download_info.value path = await download.path() # Optionally save to a known path # await download.save_as('/tmp/myfile.pdf') # Read and output file content as base64 with open(path, "rb") as f: content = base64.b64encode(f.read()).decode() print(content) ``` ```javascript Node theme={null} // Get the download URL from the link element const href = await page.getAttribute('a#download-link', 'href'); // Fetch the file in the browser context and convert to base64 const b64 = await page.evaluate(async (url) => { const resp = await fetch(url); const blob = await resp.blob(); return new Promise((resolve) => { const reader = new FileReader(); reader.onloadend = () => resolve(reader.result.split(',')[1]); reader.readAsDataURL(blob); }); }, href); process.stdout.write(b64); ``` The sandbox filesystem is ephemeral — downloaded files are lost when the session ends. To persist files, read their content within the session and save it to your own storage. Persistent profiles preserve browser state (cookies, localStorage) but not files on disk. ## agent-browser (Bash Mode) [agent-browser](https://github.com/vercel-labs/agent-browser) is a headless browser CLI pre-installed in every sandbox. Instead of writing Playwright code, agents send simple bash commands. The CLI auto-injects `--cdp` so agent-browser connects to your active session automatically. The `firecrawl browser` CLI examples below are for legacy Browser Sandbox sessions. For CLI/MCP agent workflows, prefer `firecrawl interact` or the MCP `firecrawl_interact` tool. ### Shorthand The fastest way to use browser. Both the shorthand and `execute` send commands to agent-browser automatically. The shorthand just skips `execute` and auto-launches a session if needed: ```bash theme={null} firecrawl browser "open https://example.com" firecrawl browser "snapshot" firecrawl browser "click @e5" ``` ### CLI The explicit form uses `execute`. Commands are sent to agent-browser automatically -- you don't need to type `agent-browser` or use `--bash`: ```bash Navigate & Snapshot theme={null} firecrawl browser execute "open https://example.com" firecrawl browser execute "snapshot" ``` ```bash Interact theme={null} firecrawl browser execute "click @e5" firecrawl browser execute "fill @e3 'search query'" firecrawl browser execute "scrape" ``` ### API & SDK Use `language: "bash"` to run agent-browser commands via the API or SDKs: ```bash cURL theme={null} curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "code": "agent-browser snapshot", "language": "bash" }' ``` ```javascript Node theme={null} const result = await app.browserExecute(sessionId, { code: "agent-browser snapshot", language: "bash", }); ``` ```python Python theme={null} result = app.browser_execute( session_id, code="agent-browser snapshot", language="bash", ) ``` ## Session Management ### Persistent Sessions By default, each browser session starts with a clean slate. With `profile`, you can save and reuse browser state across sessions. This is useful for staying logged in and preserving preferences. To save or select a profile, use the `profile` parameter when creating a session. | Parameter | Default | Description | | - | - | - | | `name` | — | A name for the persistent profile. Sessions with the same name share storage. | | `saveChanges` | `true` | When `true`, browser state is saved back to the profile on close. Set to `false` to load existing data without writing — useful when you need multiple concurrent readers. | Only one session can save to a profile at a time. If another session is already saving, you'll get a `409` error. You can still open the same profile with `saveChanges: false`, or try again later. The browser session state only saves when the session is closed. So we recommend closing the browser session when you are done with it so it can be reused. Once a session is closed, its session ID is no longer valid — you cannot reuse it. Instead, create a new session with the same profile name and use the new session ID returned in the response. To save and close it: ### List Sessions ### TTL Configuration Sessions have two TTL controls: | Parameter | Default | Description | | - | - | - | | `ttl` | 600s (10 min) | Maximum session lifetime (30-3600s) | | `activityTtl` | 300s (5 min) | Auto-close after inactivity (10-3600s) | ### Ad Blocking Sessions block ads, trackers, and cookie popups by default, like `blockAds` in scrape. Pass `"blockAds": false` when creating a session to load pages unfiltered. Sessions started from a scrape with interact use that scrape's `blockAds` setting. ### Location Sessions browse from the US by default. To browse from another country, pass `location` with an ISO 3166-1 alpha-2 country code when creating a session, like `location` in scrape: ```bash theme={null} curl -X POST "https://api.firecrawl.dev/v2/interact" \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "location": { "country": "GB" } }' ``` Sessions only accept a country code: `languages` and scrape's special values such as `us-generic` are rejected with a `400`. Sessions started from a scrape with interact use that scrape's `location.country`. ### Zero Data Retention Pass `"zeroDataRetention": true` when creating a session to run it with Zero Data Retention (ZDR). Firecrawl will not persist any page content or execution output beyond the lifetime of the session, and every later call to the session stays in ZDR mode. ZDR must be enabled for your team; otherwise the request returns a `403`. Session recordings and persistent profiles are not available in ZDR mode (`400`), and an existing non-ZDR session cannot be switched to ZDR (`409`). See [Interact ZDR](/features/interact#zero-data-retention-zdr) for details. ### Close a Session ## Live View Every session returns a `liveViewUrl` in the response that you can embed to watch the browser in real time. Useful for debugging, demos, or building browser-powered UIs. ```json Response theme={null} { "success": true, "id": "550e8400-e29b-41d4-a716-446655440000", "cdpUrl": "wss://browser.firecrawl.dev/cdp/550e8400...?token=abc123...", "liveViewUrl": "https://liveview.firecrawl.dev/...", "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...", "expiresAt": "2025-01-15T10:40:00Z" } ``` ```html theme={null}