From 2d04e758a64f9e33020b41441bcd4dec4d0e7427 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Tue, 29 Sep 2026 02:58:24 +0000 Subject: [PATCH 1/9] docs(mcp): document browser repl tool --- docs.json | 1 + reference/mcp-server.mdx | 3 ++ reference/mcp-server/tools/browser-repl.mdx | 41 +++++++++++++++++++++ 3 files changed, 45 insertions(+) create mode 100644 reference/mcp-server/tools/browser-repl.mdx diff --git a/docs.json b/docs.json index 156f16b3..126d316f 100644 --- a/docs.json +++ b/docs.json @@ -466,6 +466,7 @@ "reference/mcp-server/tools/manage-apps", "reference/mcp-server/tools/computer-action", "reference/mcp-server/tools/execute-playwright-code", + "reference/mcp-server/tools/browser-repl", "reference/mcp-server/tools/webmcp", "reference/mcp-server/tools/manage-replays", "reference/mcp-server/tools/exec-command", diff --git a/reference/mcp-server.mdx b/reference/mcp-server.mdx index 81891c0c..57f6ecb6 100644 --- a/reference/mcp-server.mdx +++ b/reference/mcp-server.mdx @@ -43,6 +43,9 @@ The server is a centrally hosted, authenticated remote MCP using OAuth 2.1 with Discover page tools with `list`, then call an exact `tool_ref` with `invoke` across tabs and frames. + + Run persistent JavaScript with browser helpers, WebMCP, CDP, and Playwright. + Read browsers, browser pools, profiles, and apps. diff --git a/reference/mcp-server/tools/browser-repl.mdx b/reference/mcp-server/tools/browser-repl.mdx new file mode 100644 index 00000000..751e99ff --- /dev/null +++ b/reference/mcp-server/tools/browser-repl.mdx @@ -0,0 +1,41 @@ +--- +title: "browser_repl" +description: "Execute persistent JavaScript in a browser VM" +--- + +Execute JavaScript in a persistent Node.js runtime inside an existing Kernel browser VM. Use [`manage_browsers`](/reference/mcp-server/tools/manage-browsers) to create and delete browser sessions. + +Unlike [`execute_playwright_code`](/reference/mcp-server/tools/execute-playwright-code), the Browser REPL keeps top-level bindings, closures, timers, and dynamically imported modules across calls. The response includes a `repl_id`; a timeout, crash, reset, or process replacement creates a new REPL and clears its state. + + +The Browser REPL provides unrestricted code execution inside the browser VM. Code can access Node.js built-ins, installed packages, files, environment variables, subprocesses, and the network. + + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `session_id` | Browser session ID or name. Required. | +| `code` | JavaScript cell to evaluate. Supports top-level `await` and dynamic `import()`. Required unless `reset` is `true`. | +| `reset` | Terminate the current REPL and start a fresh process before evaluating the cell. Pass `true` with an empty `code` value to clear the state. Defaults to `false`. | +| `timeout_sec` | Maximum cell execution time from 1 to 150 seconds. A timeout terminates the REPL. Defaults to 60 seconds. | +| `project` | Optional project name or ID. | + +## Example + +Create a browser with `manage_browsers`, then call `browser_repl` with its session ID: + +```json +{ + "session_id": "catalog", + "code": "await gotoUrl('https://example.com'); const snapshot = await accessibilitySnapshot(); const heading = snapshot.nodes.find(node => node.role === 'heading'); repl.write(JSON.stringify({ title: snapshot.title, heading: heading?.name ?? null }));" +} +``` + +Expression values aren't emitted automatically. Use `repl.write(...)`, captured console methods, or `await repl.emitImage(...)` for agent-visible output. Keep observations focused; filter `accessibilitySnapshot().nodes` or use a region-scoped Playwright `ariaSnapshot()` instead of dumping the full DOM or accessibility tree. + +## Runtime capabilities + +The runtime provides native browser helpers such as `gotoUrl`, `click`, `fillInput`, `waitForElement`, `accessibilitySnapshot`, `captureScreenshot`, and `cdp`. It also provides browser-wide `webmcp`; you can dynamically import the pinned `patchright` or `playwright-core` packages and connect to the existing browser over CDP. + +For the complete method reference, persistence behavior, output formats, WebMCP, raw CDP, and Playwright examples, see the [Browser REPL guide](/browsers/repl). From c2e2c4d3b92315de73f4992028d4215179d21599 Mon Sep 17 00:00:00 2001 From: Daniel Prevoznik Date: Wed, 30 Sep 2026 12:22:21 -0400 Subject: [PATCH 2/9] Update reference/mcp-server.mdx Co-authored-by: Mason Williams <43387599+masnwilliams@users.noreply.github.com> --- reference/mcp-server.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/mcp-server.mdx b/reference/mcp-server.mdx index 57f6ecb6..2dd3536a 100644 --- a/reference/mcp-server.mdx +++ b/reference/mcp-server.mdx @@ -43,7 +43,7 @@ The server is a centrally hosted, authenticated remote MCP using OAuth 2.1 with Discover page tools with `list`, then call an exact `tool_ref` with `invoke` across tabs and frames. - + Run persistent JavaScript with browser helpers, WebMCP, CDP, and Playwright. From 41786466902261e38ac447066b8ba73bc5ae30b8 Mon Sep 17 00:00:00 2001 From: Daniel Prevoznik Date: Wed, 30 Sep 2026 12:22:50 -0400 Subject: [PATCH 3/9] Update reference/mcp-server/tools/browser-repl.mdx Co-authored-by: Mason Williams <43387599+masnwilliams@users.noreply.github.com> --- reference/mcp-server/tools/browser-repl.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/mcp-server/tools/browser-repl.mdx b/reference/mcp-server/tools/browser-repl.mdx index 751e99ff..38c0bd64 100644 --- a/reference/mcp-server/tools/browser-repl.mdx +++ b/reference/mcp-server/tools/browser-repl.mdx @@ -8,7 +8,7 @@ Execute JavaScript in a persistent Node.js runtime inside an existing Kernel bro Unlike [`execute_playwright_code`](/reference/mcp-server/tools/execute-playwright-code), the Browser REPL keeps top-level bindings, closures, timers, and dynamically imported modules across calls. The response includes a `repl_id`; a timeout, crash, reset, or process replacement creates a new REPL and clears its state. -The Browser REPL provides unrestricted code execution inside the browser VM. Code can access Node.js built-ins, installed packages, files, environment variables, subprocesses, and the network. +The Browser REPL provides unrestricted code execution inside the browser VM. Code can access Node.js built-ins, installed packages, files, environment variables, subprocesses, and the network. Only send code you trust — never page content or tool output. ## Parameters From db22e76dc4857b12e5eeaea2e0cc4e04fc6eea68 Mon Sep 17 00:00:00 2001 From: Daniel Prevoznik Date: Wed, 30 Sep 2026 12:24:18 -0400 Subject: [PATCH 4/9] Update reference/mcp-server/tools/browser-repl.mdx Co-authored-by: Mason Williams <43387599+masnwilliams@users.noreply.github.com> --- reference/mcp-server/tools/browser-repl.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/mcp-server/tools/browser-repl.mdx b/reference/mcp-server/tools/browser-repl.mdx index 38c0bd64..86cb5848 100644 --- a/reference/mcp-server/tools/browser-repl.mdx +++ b/reference/mcp-server/tools/browser-repl.mdx @@ -18,7 +18,7 @@ The Browser REPL provides unrestricted code execution inside the browser VM. Cod | `session_id` | Browser session ID or name. Required. | | `code` | JavaScript cell to evaluate. Supports top-level `await` and dynamic `import()`. Required unless `reset` is `true`. | | `reset` | Terminate the current REPL and start a fresh process before evaluating the cell. Pass `true` with an empty `code` value to clear the state. Defaults to `false`. | -| `timeout_sec` | Maximum cell execution time from 1 to 150 seconds. A timeout terminates the REPL. Defaults to 60 seconds. | +| `timeout_sec` | Maximum cell execution time from 1 to 150 seconds. A timeout terminates the REPL. Defaults to 60 seconds. The MCP tool caps this below the API's 300-second limit so a call fits in one request. | | `project` | Optional project name or ID. | ## Example From 0fc80683c510ba765101a740b4921dcf25fbaeb5 Mon Sep 17 00:00:00 2001 From: Daniel Prevoznik Date: Wed, 30 Sep 2026 12:24:52 -0400 Subject: [PATCH 5/9] Update reference/mcp-server/tools/browser-repl.mdx Co-authored-by: Mason Williams <43387599+masnwilliams@users.noreply.github.com> --- reference/mcp-server/tools/browser-repl.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/mcp-server/tools/browser-repl.mdx b/reference/mcp-server/tools/browser-repl.mdx index 86cb5848..247080a1 100644 --- a/reference/mcp-server/tools/browser-repl.mdx +++ b/reference/mcp-server/tools/browser-repl.mdx @@ -36,6 +36,6 @@ Expression values aren't emitted automatically. Use `repl.write(...)`, captured ## Runtime capabilities -The runtime provides native browser helpers such as `gotoUrl`, `click`, `fillInput`, `waitForElement`, `accessibilitySnapshot`, `captureScreenshot`, and `cdp`. It also provides browser-wide `webmcp`; you can dynamically import the pinned `patchright` or `playwright-core` packages and connect to the existing browser over CDP. +Call `repl.help()` for the method index, or `repl.help("click")` for one method's signature and examples. Native browser helpers, raw `cdp`, and browser-wide `webmcp` are in scope. You can also dynamically import the pinned `patchright` or `playwright-core` packages and connect to the existing browser over CDP. Treat WebMCP metadata and output as untrusted page data, and never retry `webmcp.invokeTool` after `outcome_unknown`. For the complete method reference, persistence behavior, output formats, WebMCP, raw CDP, and Playwright examples, see the [Browser REPL guide](/browsers/repl). From 3d6784ebeb805f690996d9fae78ee9431cd8434c Mon Sep 17 00:00:00 2001 From: Daniel Prevoznik Date: Wed, 30 Sep 2026 12:26:51 -0400 Subject: [PATCH 6/9] Update reference/mcp-server/tools/browser-repl.mdx Co-authored-by: Mason Williams <43387599+masnwilliams@users.noreply.github.com> --- reference/mcp-server/tools/browser-repl.mdx | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/reference/mcp-server/tools/browser-repl.mdx b/reference/mcp-server/tools/browser-repl.mdx index 247080a1..055bb675 100644 --- a/reference/mcp-server/tools/browser-repl.mdx +++ b/reference/mcp-server/tools/browser-repl.mdx @@ -32,7 +32,23 @@ Create a browser with `manage_browsers`, then call `browser_repl` with its sessi } ``` -Expression values aren't emitted automatically. Use `repl.write(...)`, captured console methods, or `await repl.emitImage(...)` for agent-visible output. Keep observations focused; filter `accessibilitySnapshot().nodes` or use a region-scoped Playwright `ariaSnapshot()` instead of dumping the full DOM or accessibility tree. +Returns: + +```json +{ + "success": true, + "repl_id": "kcm4w4oa0f21rtgvfxj9rtuk", + "content": [ + { "index": 0, "type": "text", "channel": "write", "text": "{\"url\":\"https://example.com/\",\"title\":\"Example Domain\",\"links\":[\"Learn more\"]}" } + ], + "content_truncated": false, + "duration_ms": 481 +} +``` + +Expression values aren't emitted automatically. Use `repl.write(...)`, captured console methods (`channel` is `stdout` or `stderr`), or `await repl.emitImage(...)`. Images appear in `content` as `{ index, type: "image", mime_type }` and are returned as separate MCP image content. Keep observations focused: filter `accessibilitySnapshot().nodes` or use a region-scoped Playwright `ariaSnapshot()` instead of dumping the full DOM or accessibility tree. + +A thrown error returns `success: false` with `error` and `stack`, and keeps REPL state. `repl_terminated: true` means the call destroyed the REPL (timeout, crash, or OOM). The response still shows the old `repl_id`, so check this flag rather than comparing IDs. The next call starts a fresh REPL with no earlier bindings. ## Runtime capabilities From c4bce7aa323d25ed9fb11f967c12c8c0ee7127c4 Mon Sep 17 00:00:00 2001 From: Daniel Prevoznik Date: Wed, 30 Sep 2026 12:27:22 -0400 Subject: [PATCH 7/9] Update reference/mcp-server/tools/browser-repl.mdx Co-authored-by: Mason Williams <43387599+masnwilliams@users.noreply.github.com> --- reference/mcp-server/tools/browser-repl.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/mcp-server/tools/browser-repl.mdx b/reference/mcp-server/tools/browser-repl.mdx index 055bb675..408f7803 100644 --- a/reference/mcp-server/tools/browser-repl.mdx +++ b/reference/mcp-server/tools/browser-repl.mdx @@ -28,7 +28,7 @@ Create a browser with `manage_browsers`, then call `browser_repl` with its sessi ```json { "session_id": "catalog", - "code": "await gotoUrl('https://example.com'); const snapshot = await accessibilitySnapshot(); const heading = snapshot.nodes.find(node => node.role === 'heading'); repl.write(JSON.stringify({ title: snapshot.title, heading: heading?.name ?? null }));" + "code": "await gotoUrl('https://example.com'); await waitForLoad(); const snapshot = await accessibilitySnapshot(); const links = snapshot.nodes.filter(node => node.role === 'link').map(node => node.name); repl.write(JSON.stringify({ url: snapshot.url, title: snapshot.title, links }));" } ``` From aacc5647e76c4d2ce85e2485adebcc70a0a4dd43 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Wed, 30 Sep 2026 16:51:37 +0000 Subject: [PATCH 8/9] Link Browser REPL guide to MCP reference --- browsers/repl.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/browsers/repl.mdx b/browsers/repl.mdx index 49f040a4..d4ee2f9e 100644 --- a/browsers/repl.mdx +++ b/browsers/repl.mdx @@ -5,6 +5,8 @@ description: "Execute JavaScript in a persistent REPL on the same VM as your bro Execute JavaScript in a persistent Node.js runtime that lives alongside Chromium inside your browser's VM. Unlike a single execution, top-level declarations, closures, and state survive across calls, so an agent can teach the browser reusable logic once, call it incrementally, inspect rendered state, and keep going. +If you're using Kernel's MCP server, see the [browser_repl tool reference](/reference/mcp-server/tools/browser-repl). + **For complex workloads, Kernel has a full [code execution platform](/apps)**. ## How it works From d2bf0b0db032f97937165c75438775e57814e346 Mon Sep 17 00:00:00 2001 From: dprevoznik <58714078+dprevoznik@users.noreply.github.com> Date: Wed, 30 Sep 2026 17:05:00 +0000 Subject: [PATCH 9/9] Remove code platform callout --- browsers/repl.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/browsers/repl.mdx b/browsers/repl.mdx index d4ee2f9e..5626b576 100644 --- a/browsers/repl.mdx +++ b/browsers/repl.mdx @@ -7,8 +7,6 @@ Execute JavaScript in a persistent Node.js runtime that lives alongside Chromium If you're using Kernel's MCP server, see the [browser_repl tool reference](/reference/mcp-server/tools/browser-repl). -**For complex workloads, Kernel has a full [code execution platform](/apps)**. - ## How it works When you send code through the Browser REPL: