Playwright Execution

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
Every call runs in an executor. Calls without executor share the default executor and the active tab; named executors each own a tab and run concurrently with each other

Quick example

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"

from kernel import Kernel

kernel = Kernel()

# Create a browser
kernel_browser = kernel.browsers.create()

# Execute Playwright code
response = kernel.browsers.playwright.execute(
    id=kernel_browser.session_id,
    code="""
        await page.goto('https://example.com')
        return await page.title()
    """
)

print(response.result)  # "Example Domain"

package main

import (
	"context"
	"fmt"

	"github.com/kernel/kernel-go-sdk"
)

func main() {
	ctx := context.Background()
	client := kernel.NewClient()

	// Create a browser
	kernelBrowser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{})
	if err != nil {
		panic(err)
	}

	// Execute Playwright code
	response, err := client.Browsers.Playwright.Execute(ctx, kernelBrowser.SessionID, kernel.BrowserPlaywrightExecuteParams{
		Code: `
			await page.goto('https://example.com');
			return await page.title();
		`,
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(response.Result) // "Example Domain"
}

kernel browsers playwright execute <session_id> 'await page.goto("https://www.onkernel.com"); return page.title();'

Available variables

Your code has access to these objects:

page - The page the executor is bound to: the active tab in the default executor, or the named executor’s own tab (see Executors)
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.

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 }
    );
    if (invocation.status === 'awaiting_submission') {
      return { invocation, next_step: 'Inspect the form, confirm, then submit without reinvoking.' };
    }
    return { invocation, tools: await webmcp.listTools() };
  `,
  timeout_sec: 10,
}, { maxRetries: 0 });
console.log(response);

response = kernel.with_options(max_retries=0).browsers.playwright.execute(
    session_id,
    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 }
        );
        if (invocation.status === 'awaiting_submission') {
          return { invocation, next_step: 'Inspect the form, confirm, then submit without reinvoking.' };
        }
        return { invocation, tools: await webmcp.listTools() };
    """,
    timeout_sec=10,
)
print(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 result: completed, canceled, error, or awaiting_submission. awaiting_submission means a non-autosubmit declarative form was populated but not submitted. Inspect the form in its tab or frame, obtain any required confirmation, then submit through Playwright or computer interaction and verify the resulting page. Don’t invoke the tool again to submit it. See handling a populated form. 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:

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" }

response = kernel.browsers.playwright.execute(
    id=session_id,
    code="""
        await page.goto('https://example.com')
        title = await page.title()
        url = page.url()
        return {'title': title, 'url': url}
    """
)

print(response.result)  # {'title': 'Example Domain', 'url': 'https://example.com'}

response, err := client.Browsers.Playwright.Execute(ctx, sessionID, kernel.BrowserPlaywrightExecuteParams{
	Code: `
		await page.goto('https://example.com');
		const title = await page.title();
		const url = page.url();
		return { title, url };
	`,
})
if err != nil {
	panic(err)
}

fmt.Println(response.Result) // map[title:Example Domain url:https://example.com]

Executors

Every call runs in an executor: a dedicated Node.js process in the browser’s VM with its own connection to Chromium. Calls on the same executor run one at a time, in the order they arrive. Calls on different executors run concurrently, and a timeout, crash, or blocked event loop in one executor doesn’t affect the others. Use named executors to drive several tabs of one browser in parallel. Give each independent task its own executor name, and reuse a name for the sequential steps of one task.

The default executor

Calls without executor run in the executor named default, which always exists. Passing executor: "default" is the same as omitting it. In the default executor, page is bound to an active tab reported by Chrome (the foreground tab in single-window sessions). Use browser.contexts() to select a context or page explicitly.

Named executors

Pass any other name (^[A-Za-z0-9_-]{1,64}$) to run the call in a named executor. The first call with a new name creates it. Each named executor owns a tab: its first call opens a new background tab in the default browser context, and page is bound to that tab on every later call while it stays open. Opening it doesn’t change the active tab of an existing window. If the tab is closed, the next call opens a new one. Ownership only decides what page is bound to. Executor code can still reach other tabs through context and browser. The response includes a tab object with the tab page was bound to:

{
  "success": true,
  "result": "Example Domain",
  "tab": { "target_id": "8F2C1D4E9A7B3C6D5E1F2A3B4C5D6E7F", "created": true }
}

created is true when this call opened the tab. tab is absent if the call failed before binding a tab.

Run tasks in parallel

This example runs two tasks at the same time in two named executors, reuses one of them, then lists and deletes an executor. It uses an existing session and client, as in the examples above.

const task = (executor: string, url: string) =>
  kernel.browsers.playwright.execute(sessionId, {
    executor,
    code: `
      await page.goto(${JSON.stringify(url)});
      return { title: await page.title(), url: page.url() };
    `,
    timeout_sec: 10,
  });

// Each task opens its own background tab; both run concurrently
const [docs, home] = await Promise.all([
  task('docs', 'https://www.kernel.sh/docs/'),
  task('home', 'https://www.kernel.sh/'),
]);
console.log(docs.result, docs.tab); // { title: ..., url: ... } { target_id: '...', created: true }

// A later call on the same executor reuses its tab
const again = await kernel.browsers.playwright.execute(sessionId, {
  executor: 'docs',
  code: 'return page.url();',
});
console.log(again.tab?.created); // false

// Inspect and clean up; the default executor is always listed first
const { executors } = await kernel.browsers.playwright.executors.list(sessionId);
console.log(executors.map(({ name, busy, url }) => ({ name, busy, url })));

await kernel.browsers.playwright.executors.delete('home', {
  id_or_name: sessionId,
  close_tab: true,
});

import asyncio

from kernel import AsyncKernel

kernel = AsyncKernel()


async def task(executor: str, url: str):
    return await kernel.browsers.playwright.execute(
        session_id,
        executor=executor,
        code=f"""
            await page.goto({url!r});
            return {{ title: await page.title(), url: page.url() }};
        """,
        timeout_sec=10,
    )


async def main():
    # Each task opens its own background tab; both run concurrently
    docs, home = await asyncio.gather(
        task("docs", "https://www.kernel.sh/docs/"),
        task("home", "https://www.kernel.sh/"),
    )
    print(docs.result, docs.tab.created)  # {'title': ..., 'url': ...} True

    # A later call on the same executor reuses its tab
    again = await kernel.browsers.playwright.execute(
        session_id,
        executor="docs",
        code="return page.url();",
    )
    print(again.tab.created)  # False

    # Inspect and clean up; the default executor is always listed first
    listing = await kernel.browsers.playwright.executors.list(session_id)
    print([(e.name, e.busy, e.url) for e in listing.executors])

    await kernel.browsers.playwright.executors.delete(
        "home",
        id_or_name=session_id,
        close_tab=True,
    )


asyncio.run(main())

// Add "sync" to the imports from the example above
task := func(executor, url string) (*kernel.BrowserPlaywrightExecuteResponse, error) {
	return client.Browsers.Playwright.Execute(ctx, sessionID, kernel.BrowserPlaywrightExecuteParams{
		Executor: kernel.String(executor),
		Code: fmt.Sprintf(`
			await page.goto(%q);
			return { title: await page.title(), url: page.url() };
		`, url),
		TimeoutSec: kernel.Int(10),
	})
}

// Each task opens its own background tab; both run concurrently
var wg sync.WaitGroup
results := make([]*kernel.BrowserPlaywrightExecuteResponse, 2)
for i, t := range []struct{ executor, url string }{
	{"docs", "https://www.kernel.sh/docs/"},
	{"home", "https://www.kernel.sh/"},
} {
	wg.Add(1)
	go func() {
		defer wg.Done()
		response, err := task(t.executor, t.url)
		if err != nil {
			panic(err)
		}
		results[i] = response
	}()
}
wg.Wait()
fmt.Println(results[0].Result, results[0].Tab.TargetID, results[0].Tab.Created)

// A later call on the same executor reuses its tab
again, err := client.Browsers.Playwright.Execute(ctx, sessionID, kernel.BrowserPlaywrightExecuteParams{
	Executor: kernel.String("docs"),
	Code:     `return page.url();`,
})
if err != nil {
	panic(err)
}
fmt.Println(again.Tab.Created) // false

// Inspect and clean up; the default executor is always listed first
listing, err := client.Browsers.Playwright.Executors.List(ctx, sessionID)
if err != nil {
	panic(err)
}
for _, e := range listing.Executors {
	fmt.Println(e.Name, e.Busy, e.URL)
}

err = client.Browsers.Playwright.Executors.Delete(ctx, "home", kernel.BrowserPlaywrightExecutorDeleteParams{
	IDOrName: sessionID,
	CloseTab: kernel.Bool(true),
})
if err != nil {
	panic(err)
}

Limits

A browser can have at most 8 named executors; the default executor doesn’t count. A call that would create a ninth returns 409 with a message and an executors array listing the current executors, so you can delete one and retry. Named executors aren’t removed automatically while the browser runs. They’re removed and their tabs closed when the browser shuts down. Delete executors you’re done with so long-lived browsers don’t hit the limit. A call with executor to a browser whose image predates executors fails with 400. Calls without executor work on every image.

List and delete executors

GET /browsers/{id_or_name}/playwright/executors returns the browser’s executors, default first. Each entry has name, busy (whether a call is currently running on the executor), created_at, and last_used_at; named executors with an open tab also report target_id and url. DELETE /browsers/{id_or_name}/playwright/executors/{name} stops the executor’s process and returns 204. It closes the executor’s tab unless you pass close_tab=false. A call running on the executor fails with an error saying the executor was deleted, and the name can be reused afterwards. Unknown names return 404. Deleting default restarts it instead of removing it: its process is stopped, and queued and later calls run on a new process. It owns no tab, so close_tab has no effect. Use this to recover the default executor from a stuck state.

Timeouts and crashes

After a timeout, the executor keeps its process but drops its browser connection, so code abandoned by the timeout can’t keep driving the browser. After a crash or a blocked event loop, the next call on that executor starts a fresh process. Either way, other executors keep running.

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:

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

response = kernel.browsers.playwright.execute(
    session_id,
    code="""
        await page.goto('https://example.com');
        return await page.title();
    """,
    timeout_sec=10,
)

response, err := client.Browsers.Playwright.Execute(ctx, sessionID, kernel.BrowserPlaywrightExecuteParams{
	Code: `
		await page.goto('https://example.com');
		return await page.title();
	`,
	TimeoutSec: kernel.Int(10),
})
if err != nil {
	panic(err)
}
_ = response

Error handling

The response includes error information if execution fails:

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);
}

response = kernel.browsers.playwright.execute(
    id=session_id,
    code="""
        await page.goto('https://invalid-url')
        return await page.title()
    """
)

if not response.success:
    print('Error:', response.error)
    print('Stderr:', response.stderr)

response, err := client.Browsers.Playwright.Execute(ctx, sessionID, kernel.BrowserPlaywrightExecuteParams{
	Code: `
		await page.goto('https://invalid-url');
		return await page.title();
	`,
})
if err != nil {
	panic(err)
}

if !response.Success {
	fmt.Println("Error:", response.Error)
	fmt.Println("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', 'user@example.com');
      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.

Why playwright execution over a direct CDP connection

If you’re reaching for Playwright, prefer the execution API over connectOverCDP. Same Playwright API you already know, none of the setup.

Run from anywhere. No playwright package to version-pin, no Chromium download, no CDP connection to manage. Send the code, get the result.
Co-located with the browser. Code runs in the same VM as the browser — no network hop between your script and the page, fewer flakes.
Patchright by default. Hardened against bot detection out of the box.
Full Playwright API. page, context, and browser are all in scope. Anything Playwright can do — DOM queries, file uploads, full-page screenshots — works here.
Returns values. return from your code and the result comes back in the response. Easy to use as an agent tool.

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.

Accessibility tree

Get a YAML accessibility-tree snapshot of the page, the same ref-based format AI browser tools like Playwright MCP use:

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

console.log(response.result);
// - generic [ref=f1e2]:
//   - heading "Example Domain" [level=1] [ref=f1e3]
//   - paragraph [ref=f1e4]: This domain is for use in documentation examples...

Each node’s ref (e.g. f1e3) can be passed to page.locator('aria-ref=f1e3') in a later request to act on that exact element.

Overview

Start building

How it works

Partnering with KERNEL

Playwright Execution

How it works

Quick example

Available variables

WebMCP helpers

Returning values

Executors

The default executor

Named executors

Run tasks in parallel

Limits

List and delete executors

Timeouts and crashes

Timeout configuration

Error handling

Use cases

Web scraping

Form automation

Testing and validation

Screenshots

Why playwright execution over a direct CDP connection

MCP server integration

Accessibility tree

​How it works

​Quick example

​Available variables

​WebMCP helpers

​Returning values

​Executors

​The default executor

​Named executors

​Run tasks in parallel

​Limits

​List and delete executors

​Timeouts and crashes

​Timeout configuration

​Error handling

​Use cases

​Web scraping

​Form automation

​Testing and validation

​Screenshots

​Why playwright execution over a direct CDP connection

​MCP server integration

​Accessibility tree

How it works

Quick example

Available variables

WebMCP helpers

Returning values

Executors

The default executor

Named executors

Run tasks in parallel

Limits

List and delete executors

Timeouts and crashes

Timeout configuration

Error handling

Use cases

Web scraping

Form automation

Testing and validation

Screenshots

Why playwright execution over a direct CDP connection

MCP server integration

Accessibility tree