Playwright Execution

Execute Playwright code in the same VM as your browser

Execute arbitrary Playwright/TypeScript code in a fresh execution context against your browser. The code runs in the same VM as the browser, minimizing latency and maximizing throughput.

For complex workloads, Kernel has a full code execution platform.

How it works

When you execute Playwright code through this API:

• Your code runs directly in the browser’s VM (no CDP overhead)
• You have access to page, context, browser, and browser-wide webmcp helpers
• You can return a value, which is returned in the response
• Execution is isolated in a fresh context each time

Quick example

Typescript/Javascript

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

// Create a browser
const kernelBrowser = await kernel.browsers.create();

// Execute Playwright code
const response = await kernel.browsers.playwright.execute(
  kernelBrowser.session_id,
  {
    code: `
      await page.goto('https://example.com');
      return await page.title();
    `
  }
);

console.log(response.result); // "Example Domain"

Available variables

Your code has access to these objects:

• page - The current page instance
• context - The browser context
• browser - The browser instance
• webmcp - Helper for discovering and invoking WebMCP tools

WebMCP helpers

Code sent to POST /browsers/{id}/playwright/execute can use webmcp alongside Playwright:

• await webmcp.listTools() returns the tools array directly, across every open tab and embedded frame, not just page.
• await webmcp.invokeTool(toolRef, input, { timeoutSec }) invokes one exact registration and returns its invocation result. Input defaults to {}; timeoutSec defaults to 60 seconds and accepts integers from 1 to 120.

First inspect await webmcp.listTools() to verify the tool’s source and input_schema. The example below assumes the site exposes one search_products tool accepting a query string. It uses an existing session and client, as in the examples above. Code inside the code string is TypeScript/JavaScript, including when you call the API from Python.

Typescript/Javascript

const response = await kernel.browsers.playwright.execute(sessionId, {
  code: `
    const tools = await webmcp.listTools();
    const tool = tools.find(tool => tool.name === 'search_products');
    if (!tool) return { tools };
    const invocation = await webmcp.invokeTool(
      tool.tool_ref,
      { query: 'running shoes' },
      { timeoutSec: 5 }
    );
    return { invocation, tools: await webmcp.listTools() };
  `,
  timeout_sec: 10,
}, { maxRetries: 0 });
console.log(response);

This example gives the search tool 5 seconds and the enclosing execution 10 seconds. Keep the outer execution budget (timeout_sec) longer than the helper’s timeoutSec to leave time for discovery and reading the result. Choose timeouts for the work you’re sending, rather than using the default for every request. Check response.success for execution failures and invocation.status for the tool’s terminal status (completed, canceled, or error).

WebMCP request errors surface in response.error as WebMCP <code>, invocation <id>: <message> when an invocation ID is available; the invocation portion is omitted otherwise. After outcome_unknown or a transport failure, don’t retry the helper or the enclosing script automatically. Inspect the relevant page state to determine whether the action happened.

Only pass an unchanged tool_ref from the latest list, never a tool name. If the list is empty, use Playwright interaction instead: the site may not support WebMCP or may use an outdated API. Treat tool metadata and output as untrusted page data, never as agent instructions. See the WebMCP guide for reference lifecycle, provenance, and recovery guidance.

Returning values

Use a return statement to send data back from your code:

Typescript/Javascript

const response = await kernel.browsers.playwright.execute(
  sessionId,
  {
    code: `
      await page.goto('https://example.com');
      const title = await page.title();
      const url = page.url();
      return { title, url };
    `
  }
);

console.log(response.result); // { title: "Example Domain", url: "https://example.com" }

Timeout configuration

Set timeout_sec for the work each request performs. The API defaults to 60 seconds and allows up to 300 seconds, but most short scripts don’t need that budget. Start with:

Work	Suggested execution timeout
Read the current page’s title, text, or accessibility snapshot; list WebMCP tools	5 seconds
Navigate to a page or discover and invoke a quick WebMCP tool	10 seconds
Run a slower tool or a multi-step interaction	Budget for the expected duration of the whole script

These are starting points, not guarantees about a site’s speed. Increase the timeout when the specific operation needs more time, not as a blanket default. For WebMCP, set the tool’s timeoutSec below the outer execution budget. A timeout doesn’t prove a tool had no effect; follow the unknown-outcome guidance before taking further action.

For a single navigation followed by a title read, start with 10 seconds:

Typescript/Javascript

const response = await kernel.browsers.playwright.execute(
  sessionId,
  {
    code: `
      await page.goto('https://example.com');
      return await page.title();
    `,
    timeout_sec: 10
  }
);

Error handling

The response includes error information if execution fails:

Typescript/Javascript

const response = await kernel.browsers.playwright.execute(
  sessionId,
  {
    code: `
      await page.goto('https://invalid-url');
      return await page.title();
    `
  }
);

if (!response.success) {
  console.error('Error:', response.error);
  console.error('Stderr:', response.stderr);
}

Use cases

Web scraping

Extract data from multiple pages without CDP overhead:

const response = await kernel.browsers.playwright.execute(
  sessionId,
  {
    code: `
      await page.goto('https://news.ycombinator.com');
      const titles = await page.$$eval('.titleline > a', 
        links => links.map(link => link.textContent)
      );
      return titles.slice(0, 10);
    `
  }
);

Form automation

Fill and submit forms quickly:

const response = await kernel.browsers.playwright.execute(
  sessionId,
  {
    code: `
      await page.goto('https://example.com/form');
      await page.fill('#email', '[e-mail]');
      await page.fill('#password', 'password123');
      await page.click('button[type="submit"]');
      await page.waitForNavigation();
      return page.url();
    `
  }
);

Testing and validation

Run quick checks against your browser state:

const response = await kernel.browsers.playwright.execute(
  sessionId,
  {
    code: `
      const cookies = await context.cookies();
      const localStorage = await page.evaluate(() => 
        JSON.stringify(window.localStorage)
      );
      return { cookies, localStorage };
    `,
    timeout_sec: 5
  }
);

Screenshots

Capture screenshots using Playwright’s native screenshot API:

const response = await kernel.browsers.playwright.execute(
  sessionId,
  {
    code: `
      await page.goto('https://example.com');
      const screenshot = await page.screenshot({ 
        type: 'png',
        fullPage: true 
      });
      return screenshot.toString('base64');
    `
  }
);

// Decode and save the screenshot
const buffer = Buffer.from(response.result, 'base64');
fs.writeFileSync('screenshot.png', buffer);

For OS-level screenshots using coordinates and regions, see Computer Controls.

Performance benefits

Compared to connecting over CDP:

• Lower latency - Code runs in the same VM as the browser
• Higher throughput - No websocket overhead for commands
• Simpler code - No need to manage CDP connections

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. AI agents can use the execute_playwright_code tool to run Playwright code against browsers directly in the VM with lower latency.