Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

browser: persistentsession (#2919)

Thomas Kosmase4915199c5d7
diff --git a/apps/api/src/controllers/v2/browser.ts b/apps/api/src/controllers/v2/browser.ts
index 16f531d57..88d2c7ad6 100644
--- a/apps/api/src/controllers/v2/browser.ts
+++ b/apps/api/src/controllers/v2/browser.ts
@@ -1,3 +1,4 @@
+import { createHash } from "crypto";
import { v7 as uuidv7 } from "uuid";
import { Request, Response } from "express";
import { z } from "zod";
@@ -40,6 +41,10 @@ const browserCreateRequestSchema = z.object({
ttl: z.number().min(30).max(3600).default(300),
activityTtl: z.number().min(10).max(3600).default(120),
streamWebView: z.boolean().default(true),
+ persistentSession: z.object({
+ name: z.string().min(1).max(128),
+ writeMode: z.enum(["readonly", "readwrite"]).default("readwrite"),
+ }).optional(),
});
type BrowserCreateRequest = z.infer<typeof browserCreateRequestSchema>;
@@ -114,6 +119,14 @@ function browserServiceHeaders(
return headers;
}
+class BrowserServiceError extends Error {
+ status: number;
+ constructor(status: number, message: string) {
+ super(message);
+ this.status = status;
+ }
+}
+
/**
* Call the browser service and return parsed JSON.
* Throws on non-2xx responses.
@@ -132,7 +145,8 @@ async function browserServiceRequest<T>(
if (!res.ok) {
const text = await res.text();
- throw new Error(
+ throw new BrowserServiceError(
+ res.status,
`Browser service ${method} ${path} failed (${res.status}): ${text}`,
);
}
@@ -193,7 +207,7 @@ export async function browserCreateController(
req.body = browserCreateRequestSchema.parse(req.body);
- const { ttl, activityTtl, streamWebView } = req.body;
+ const { ttl, activityTtl, streamWebView, persistentSession } = req.body;
if (!config.BROWSER_SERVICE_URL) {
return res.status(503).json({
@@ -237,6 +251,19 @@ export async function browserCreateController(
let svcResponse: BrowserServiceCreateResponse | undefined;
let lastCreateError: unknown;
+ // Build persistentStorage from persistentSession if provided
+ let persistentStorage: { uniqueId: string; write: boolean } | undefined;
+ if (persistentSession) {
+ const teamHash = createHash("sha256")
+ .update(req.auth.team_id)
+ .digest("hex")
+ .slice(0, 16);
+ persistentStorage = {
+ uniqueId: `${teamHash}_${persistentSession.name}`,
+ write: persistentSession.writeMode === "readwrite",
+ };
+ }
+
for (let attempt = 1; attempt <= MAX_CREATE_RETRIES; attempt++) {
try {
svcResponse = await browserServiceRequest<BrowserServiceCreateResponse>(
@@ -245,10 +272,23 @@ export async function browserCreateController(
{
ttl,
...(activityTtl !== undefined ? { activityTtl } : {}),
+ ...(persistentStorage !== undefined ? { persistentStorage } : {}),
},
);
break;
} catch (err) {
+ // 409 means the persistent session profile is locked by another writer — don't retry
+ if (err instanceof BrowserServiceError && err.status === 409) {
+ logger.warn("Persistent session profile is locked", {
+ persistentSessionName: persistentSession?.name,
+ error: err,
+ });
+ return res.status(409).json({
+ success: false,
+ error: "Another session is currently writing to this persistent session profile. Only one writer is allowed at a time. You can still access it with writeMode \"readonly\", or try again later.",
+ });
+ }
+
lastCreateError = err;
logger.warn("Browser session creation attempt failed", {
attempt,
diff --git a/apps/js-sdk/firecrawl/src/v2/methods/browser.ts b/apps/js-sdk/firecrawl/src/v2/methods/browser.ts
index a1cb62fd6..a0c6d9406 100644
--- a/apps/js-sdk/firecrawl/src/v2/methods/browser.ts
+++ b/apps/js-sdk/firecrawl/src/v2/methods/browser.ts
@@ -13,12 +13,17 @@ export async function browser(
ttl?: number;
activityTtl?: number;
streamWebView?: boolean;
+ persistentSession?: {
+ name: string;
+ writeMode?: "readonly" | "readwrite";
+ };
} = {}
): Promise<BrowserCreateResponse> {
const body: Record<string, unknown> = {};
if (args.ttl != null) body.ttl = args.ttl;
if (args.activityTtl != null) body.activityTtl = args.activityTtl;
if (args.streamWebView != null) body.streamWebView = args.streamWebView;
+ if (args.persistentSession != null) body.persistentSession = args.persistentSession;
try {
const res = await http.post<BrowserCreateResponse>("/v2/browser", body);
diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.py
index b5a393c78..2c02299a0 100644
--- a/apps/python-sdk/firecrawl/v2/client.py
+++ b/apps/python-sdk/firecrawl/v2/client.py
@@ -984,6 +984,7 @@ class FirecrawlClient:
ttl: Optional[int] = None,
activity_ttl: Optional[int] = None,
stream_web_view: Optional[bool] = None,
+ persistent_session: Optional[Dict[str, Any]] = None,
):
"""Create a new browser session.
@@ -991,6 +992,8 @@ class FirecrawlClient:
ttl: Total time-to-live in seconds (30-3600, default 300)
activity_ttl: Inactivity TTL in seconds (10-3600)
stream_web_view: Whether to enable webview streaming
+ persistent_session: Persistent session config with ``name`` (str) and
+ optional ``write_mode`` (``"readonly"`` | ``"readwrite"``, default ``"readwrite"``)
Returns:
BrowserCreateResponse with session id and CDP URL
@@ -1000,6 +1003,7 @@ class FirecrawlClient:
ttl=ttl,
activity_ttl=activity_ttl,
stream_web_view=stream_web_view,
+ persistent_session=persistent_session,
)
def browser_execute(
diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.py
index cd7afbc49..58197837b 100644
--- a/apps/python-sdk/firecrawl/v2/client_async.py
+++ b/apps/python-sdk/firecrawl/v2/client_async.py
@@ -468,6 +468,7 @@ class AsyncFirecrawlClient:
ttl: Optional[int] = None,
activity_ttl: Optional[int] = None,
stream_web_view: Optional[bool] = None,
+ persistent_session: Optional[Dict[str, Any]] = None,
):
"""Create a new browser session.
@@ -475,6 +476,8 @@ class AsyncFirecrawlClient:
ttl: Total time-to-live in seconds (30-3600, default 300)
activity_ttl: Inactivity TTL in seconds (10-3600)
stream_web_view: Whether to enable webview streaming
+ persistent_session: Persistent session config with ``name`` (str) and
+ optional ``write_mode`` (``"readonly"`` | ``"readwrite"``, default ``"readwrite"``)
Returns:
BrowserCreateResponse with session id and CDP URL
@@ -484,6 +487,7 @@ class AsyncFirecrawlClient:
ttl=ttl,
activity_ttl=activity_ttl,
stream_web_view=stream_web_view,
+ persistent_session=persistent_session,
)
async def browser_execute(
diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/browser.py b/apps/python-sdk/firecrawl/v2/methods/aio/browser.py
index e9d8e4715..5ae662540 100644
--- a/apps/python-sdk/firecrawl/v2/methods/aio/browser.py
+++ b/apps/python-sdk/firecrawl/v2/methods/aio/browser.py
@@ -4,7 +4,7 @@ Async browser session methods for Firecrawl v2 API.
Provides async create, execute, delete, and list operations for browser sessions.
"""
-from typing import Any, Dict, List, Literal, Optional
+from typing import Any, Dict, Literal, Optional
from ...types import (
BrowserCreateResponse,
@@ -53,6 +53,7 @@ async def browser(
ttl: Optional[int] = None,
activity_ttl: Optional[int] = None,
stream_web_view: Optional[bool] = None,
+ persistent_session: Optional[Dict[str, Any]] = None,
) -> BrowserCreateResponse:
"""Create a new browser session.
@@ -61,6 +62,8 @@ async def browser(
ttl: Total time-to-live in seconds (30-3600, default 300)
activity_ttl: Inactivity TTL in seconds (10-3600)
stream_web_view: Whether to enable webview streaming
+ persistent_session: Persistent session config with ``name`` (str) and
+ optional ``write_mode`` (``"readonly"`` | ``"readwrite"``, default ``"readwrite"``)
Returns:
BrowserCreateResponse with session id and CDP URL
@@ -72,6 +75,11 @@ async def browser(
body["activityTtl"] = activity_ttl
if stream_web_view is not None:
body["streamWebView"] = stream_web_view
+ if persistent_session is not None:
+ body["persistentSession"] = {
+ "name": persistent_session["name"],
+ "writeMode": persistent_session.get("write_mode", "readwrite"),
+ }
resp = await client.post("/v2/browser", body)
payload = _normalize_browser_create_response(resp.json())
diff --git a/apps/python-sdk/firecrawl/v2/methods/browser.py b/apps/python-sdk/firecrawl/v2/methods/browser.py
index 1215be448..b667fca4d 100644
--- a/apps/python-sdk/firecrawl/v2/methods/browser.py
+++ b/apps/python-sdk/firecrawl/v2/methods/browser.py
@@ -54,6 +54,7 @@ def browser(
ttl: Optional[int] = None,
activity_ttl: Optional[int] = None,
stream_web_view: Optional[bool] = None,
+ persistent_session: Optional[Dict[str, Any]] = None,
) -> BrowserCreateResponse:
"""Create a new browser session.
@@ -62,6 +63,8 @@ def browser(
ttl: Total time-to-live in seconds (30-3600, default 300)
activity_ttl: Inactivity TTL in seconds (10-3600)
stream_web_view: Whether to enable webview streaming
+ persistent_session: Persistent session config with ``name`` (str) and
+ optional ``write_mode`` (``"readonly"`` | ``"readwrite"``, default ``"readwrite"``)
Returns:
BrowserCreateResponse with session id and CDP URL
@@ -73,6 +76,11 @@ def browser(
body["activityTtl"] = activity_ttl
if stream_web_view is not None:
body["streamWebView"] = stream_web_view
+ if persistent_session is not None:
+ body["persistentSession"] = {
+ "name": persistent_session["name"],
+ "writeMode": persistent_session.get("write_mode", "readwrite"),
+ }
resp = client.post("/v2/browser", body)
if not resp.ok: