kernel · dprevoznik · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/browsers/playwright-execution.mdx b/browsers/playwright-execution.mdx
@@ -353,4 +353,4 @@ This makes it ideal for one-off operations where you need maximum speed.
 
 ## MCP server integration
 
-This feature is available as a tool in our [MCP server](/reference/mcp-server). AI agents can use the `execute_playwright_code` tool to run Playwright code against browsers with automatic video replay and cleanup.
+This feature is available as a tool in our [MCP server](/reference/mcp-server). AI agents can use the `execute_playwright_code` tool to run Playwright code against browsers directly in the VM with lower latency.
diff --git a/docs.json b/docs.json
@@ -337,6 +337,7 @@
               "reference/mcp-server/tools/manage-apps",
               "reference/mcp-server/tools/computer-action",
               "reference/mcp-server/tools/execute-playwright-code",
+              "reference/mcp-server/tools/manage-replays",
               "reference/mcp-server/tools/exec-command",
               "reference/mcp-server/tools/search-docs"
             ]

diff --git a/reference/mcp-server/examples.mdx b/reference/mcp-server/examples.mdx
@@ -15,9 +15,21 @@ Assistant: I'll execute your web-scraper action with reddit.com as the target.
 
 ```
 Human: Go to example.com and get me the page title
-Assistant: I'll execute Playwright code to navigate to the site and retrieve the title.
-[Uses execute_playwright_code tool with code: "await page.goto('https://example.com'); return await page.title();"]
-Returns: { success: true, result: "Example Domain", replay_url: "https://..." }
+Assistant: I'll create a browser session, then execute Playwright code to navigate to the site and retrieve the title.
+[Uses manage_browsers tool with action: "create" to launch a session]
+[Uses execute_playwright_code tool with session_id and code: "await page.goto('https://example.com'); return await page.title();"]
+Returns: { success: true, result: "Example Domain" }
+[Uses manage_browsers tool with action: "delete" to clean up the session]
+```
+
+## Record a video replay of an automation
+
+```
+Human: Record a video while you scrape this page
+Assistant: I'll start a replay recording, run the automation, then stop it.
+[Uses manage_replays tool with action: "start" and the session_id]
+[Uses execute_playwright_code tool to run the automation]
+[Uses manage_replays tool with action: "stop" to end the recording]
 ```
 
 ## Set up browser profiles for authentication

diff --git a/reference/mcp-server/tools/execute-playwright-code.mdx b/reference/mcp-server/tools/execute-playwright-code.mdx
@@ -3,7 +3,9 @@ title: "execute_playwright_code"
 description: "Run Playwright/TypeScript code against a browser session"
 ---
 
-Execute Playwright/TypeScript automation code against a Kernel browser session. If `session_id` is provided, uses that existing browser; otherwise creates a new one. Returns the result with a video replay URL, and auto-cleans up browsers it creates.
+Execute Playwright/TypeScript automation code against an existing Kernel browser session. This tool is a thin passthrough: it runs your code in the browser's VM and returns the result. It does not manage browser lifecycle — create and delete sessions with [`manage_browsers`](/reference/mcp-server/tools/manage-browsers).
+
+<Note>`session_id` is required. Unlike earlier versions, this tool no longer creates a browser when `session_id` is omitted, and no longer deletes the browser after execution. Create a session with `manage_browsers` (action `create`), pass its `session_id` here, then delete it with `manage_browsers` when done.</Note>
 
 <Tip>Use `computer_action` with the `screenshot` action instead of `page.screenshot()` in your code. For a comprehensive page state snapshot, use `await page._snapshotForAI()`.</Tip>
 
@@ -12,12 +14,13 @@ Execute Playwright/TypeScript automation code against a Kernel browser session.
 | Parameter | Description |
 |-----------|-------------|
 | `code` | Playwright/TypeScript code with a `page` object in scope. Required. |
-| `session_id` | Existing browser session ID. If omitted, a new browser is created and cleaned up after execution. |
+| `session_id` | Existing browser session ID to run against. Required. |
 
 ## Example
 
 ```json
 {
+  "session_id": "session_abc123",
   "code": "await page.goto('https://example.com'); return await page.title();"
 }
 ```
@@ -27,7 +30,8 @@ Returns:
 ```json
 {
   "success": true,
-  "result": "Example Domain",
-  "replay_url": "https://..."
+  "result": "Example Domain"
 }
 ```
+
+<Tip>To capture a video recording around your automation, start a recording with [`manage_replays`](/reference/mcp-server/tools/manage-replays) before your calls and stop it when done.</Tip>
diff --git a/reference/mcp-server/tools/manage-browsers.mdx b/reference/mcp-server/tools/manage-browsers.mdx
@@ -5,6 +5,8 @@ description: "Create, list, get, and delete browser sessions"
 
 Manage browser sessions on the Kernel platform. Created browsers run in isolated VMs and support headless/stealth modes, profiles, proxies, viewports, extensions, and SSH tunneling.
 
+Browser lifecycle lives here: `create` a session before running [`execute_playwright_code`](/reference/mcp-server/tools/execute-playwright-code) against it, and `delete` it when you're done.
+
 ## Actions
 
 | Action | Description |

diff --git a/reference/mcp-server/tools/manage-replays.mdx b/reference/mcp-server/tools/manage-replays.mdx
@@ -0,0 +1,37 @@
+---
+title: "manage_replays"
+description: "Start, stop, and list video replay recordings for a browser session"
+---
+
+Record video replays of a browser session. Recording is opt-in and session-scoped: start a recording once, run your automation (for example with [`execute_playwright_code`](/reference/mcp-server/tools/execute-playwright-code)), then stop it.
+
+<Note>Replays require a headful session. They are not available for [headless](/browsers/headless) browsers.</Note>
+
+## Actions
+
+| Action | Description |
+|--------|-------------|
+| `start` | Begin recording a session. Returns a `replay_id`. |
+| `stop` | Stop a recording. |
+| `list` | List recordings for a session, including their view/download URLs. |
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `action` | Operation to perform: `start`, `stop`, or `list`. Required. |
+| `session_id` | Browser session ID. Required. |
+| `replay_id` | Recording ID to stop. Required for `stop`. |
+| `framerate` | (start) Frames per second for the recording. |
+| `max_duration_in_seconds` | (start) Maximum recording length in seconds. |
+| `record_audio` | (start) Capture audio in addition to video. |
+
+## Example
+
+```json
+{
+  "action": "start",
+  "session_id": "session_abc123",
+  "max_duration_in_seconds": 300
+}
+```
Original file line number	Diff line number	Diff line change
Expand Up		@@ -353,4 +353,4 @@ This makes it ideal for one-off operations where you need maximum speed.

		## MCP server integration

		This feature is available as a tool in our [MCP server](/reference/mcp-server). AI agents can use the `execute_playwright_code` tool to run Playwright code against browsers with automatic video replay and cleanup.
		This feature is available as a tool in our [MCP server](/reference/mcp-server). AI agents can use the `execute_playwright_code` tool to run Playwright code against browsers directly in the VM with lower latency.