> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-large-gpu-browsers.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Execute Playwright/TypeScript code against the browser > Execute arbitrary Playwright code in a fresh execution context against the browser. The code runs in the same VM as the browser, minimizing latency and maximizing throughput. It has access to 'page', 'context', 'browser', and 'webmcp' variables. Use 'webmcp.listTools()' to discover browser-wide WebMCP tools and 'webmcp.invokeTool(toolRef, input?, { timeoutSec? })' to invoke an exact registration. It can `return` a value, and this value is returned in the response. Every call runs in an executor: a dedicated Node.js process with its own browser connection. Calls on different executors run concurrently; calls on the same executor run one at a time. A timeout, crash, or blocked event loop in one executor does not affect other executors. After a timeout the executor keeps its process and drops its browser connection, so code abandoned by the timeout cannot keep driving the browser. After a crash or a blocked event loop, the next call on that executor starts a fresh process. Calls without 'executor' run in the executor named 'default', which always exists and is the same as passing 'executor: "default"'. In the default executor, 'page' is bound to an active tab reported by Chrome. In single-window sessions, this is the foreground tab. When multiple browser windows are open, Chrome reports one active tab per window and the selected window is unspecified. 'context' is the BrowserContext that owns the selected page. Use 'browser.contexts()' to select a context or page explicitly. Pass any other name 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 does not change the active tab of an existing window. If the tab is closed, the next call opens a new one and reports 'tab.created: true'. Executor code can still reach other tabs through 'context' and 'browser'; ownership only decides what 'page' is bound to. Use named executors to drive several tabs of one browser in parallel. A browser can have at most 8 named executors; the default executor does not count. A call that would create another returns 409 with the current executors; delete one with DELETE /browsers/{id_or_name}/playwright/executors/{name}. Named executors are not removed automatically while the browser runs; when it shuts down, they are removed and their tabs closed. A named call to a browser whose image predates executors fails with 400 instead of running on the active tab; calls without 'executor' keep working on every image. ## OpenAPI ````yaml https://api.onkernel.com/spec.json post /browsers/{id_or_name}/playwright/execute openapi: 3.1.0 info: description: Developer tools and cloud infrastructure for AI agents to use web browsers title: Kernel API version: 0.1.0 servers: - description: API Server url: https://api.onkernel.com security: - bearerAuth: [] tags: - description: Search the web and retrieve content for selected results. name: Search - description: Create and manage browser sessions. name: Browsers - description: Control mouse, keyboard, and screen on the browser instance. name: Browser Computer Controls - description: >- Execute Playwright code against the browser instance and manage the executors it runs in. name: Browser Playwright - description: Execute JavaScript in the browser instance's persistent Browser REPL. name: Browser REPL - description: Discover and invoke native page tools across the browser instance. name: Browser WebMCP - description: Read, write, and manage files on the browser instance. name: Browser Filesystem - description: Execute and manage processes on the browser instance. name: Browser Processes - description: Record and manage browser session video replays. name: Browser Replays - description: Stream logs from the browser instance. name: Browser Logs - description: >- Stream live telemetry events from a browser session, and manage the destinations sessions export them to. name: Browser Telemetry - description: Create, list, retrieve, and delete browser profiles. name: Profiles - description: Create and manage proxy configurations for routing browser traffic. name: Proxies - description: Create, list, retrieve, and delete browser extensions. name: Extensions - description: Create and manage browser pools for acquiring and releasing browsers. name: Browser Pools - description: Inspect the identity and authorization context for the current request. name: Authentication - description: >- Create and manage auth connections for automated credential capture and login. name: Managed Auth - description: Create and manage credentials for authentication. name: Credentials - description: Configure external credential providers like 1Password. name: Credential Providers - description: List applications and versions. name: Apps - description: Create and manage app deployments and stream deployment events. name: Deployments - description: Invoke actions and stream or query invocation status and events. name: Invocations - description: Read and manage organization-level limits. name: Organization - description: | Create and manage projects for resource isolation within an organization. When projects are disabled for the organization, project operations return `404` with code `projects_disabled`. name: Projects - description: Create and manage API keys for organization and project-scoped access. name: API Keys - description: Read audit log records for the authenticated organization. name: Audit Logs - description: Resolve browser and proxy recommendations for bot-protected sites. name: Config Registry paths: /browsers/{id_or_name}/playwright/execute: post: tags: - Browser Playwright summary: Execute Playwright/TypeScript code against the browser description: > Execute arbitrary Playwright code in a fresh execution context against the browser. The code runs in the same VM as the browser, minimizing latency and maximizing throughput. It has access to 'page', 'context', 'browser', and 'webmcp' variables. Use 'webmcp.listTools()' to discover browser-wide WebMCP tools and 'webmcp.invokeTool(toolRef, input?, { timeoutSec? })' to invoke an exact registration. It can `return` a value, and this value is returned in the response. Every call runs in an executor: a dedicated Node.js process with its own browser connection. Calls on different executors run concurrently; calls on the same executor run one at a time. A timeout, crash, or blocked event loop in one executor does not affect other executors. After a timeout the executor keeps its process and drops its browser connection, so code abandoned by the timeout cannot keep driving the browser. After a crash or a blocked event loop, the next call on that executor starts a fresh process. Calls without 'executor' run in the executor named 'default', which always exists and is the same as passing 'executor: "default"'. In the default executor, 'page' is bound to an active tab reported by Chrome. In single-window sessions, this is the foreground tab. When multiple browser windows are open, Chrome reports one active tab per window and the selected window is unspecified. 'context' is the BrowserContext that owns the selected page. Use 'browser.contexts()' to select a context or page explicitly. Pass any other name 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 does not change the active tab of an existing window. If the tab is closed, the next call opens a new one and reports 'tab.created: true'. Executor code can still reach other tabs through 'context' and 'browser'; ownership only decides what 'page' is bound to. Use named executors to drive several tabs of one browser in parallel. A browser can have at most 8 named executors; the default executor does not count. A call that would create another returns 409 with the current executors; delete one with DELETE /browsers/{id_or_name}/playwright/executors/{name}. Named executors are not removed automatically while the browser runs; when it shuts down, they are removed and their tabs closed. A named call to a browser whose image predates executors fails with 400 instead of running on the active tab; calls without 'executor' keep working on every image. operationId: executePlaywrightCode parameters: - description: Browser session ID or name example: htzv5orfit78e1m2biiifpbv in: path name: id_or_name required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ExecutePlaywrightRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ExecutePlaywrightResult' description: Code executed successfully '400': $ref: '#/components/responses/BadRequest' '409': content: application/json: schema: $ref: '#/components/schemas/PlaywrightExecutorLimitError' description: The call would create a named executor beyond the per-browser limit '500': $ref: '#/components/responses/InternalError' default: $ref: '#/components/responses/BrowserProxyError' security: - bearerAuth: [] components: schemas: ExecutePlaywrightRequest: additionalProperties: false description: Request to execute Playwright code properties: code: description: > TypeScript/JavaScript code to execute. The code has access to 'page', 'context', and 'browser' variables. It runs within a function, so you can use a return statement at the end to return a value. This value is returned as the `result` property in the response. Example: "await page.goto('https://example.com'); return await page.title();" type: string executor: $ref: '#/components/schemas/PlaywrightExecutorName' timeout_sec: default: 60 description: Maximum execution time in seconds. Default is 60. maximum: 300 minimum: 1 type: integer required: - code type: object ExecutePlaywrightResult: additionalProperties: false description: Result of Playwright code execution properties: error: description: Error message if execution failed type: string result: description: The value returned by the code (if any) stderr: description: Standard error from the execution type: string stdout: description: Standard output from the execution type: string success: description: Whether the code executed successfully type: boolean tab: $ref: '#/components/schemas/PlaywrightTab' required: - success type: object PlaywrightExecutorLimitError: additionalProperties: false description: >- Returned when a call would create a named executor beyond the per-browser limit properties: executors: description: The default executor and the named executors that already exist items: $ref: '#/components/schemas/PlaywrightExecutor' type: array message: description: Human-readable error description type: string required: - message - executors type: object PlaywrightExecutorName: description: > Name of a Playwright executor. Calls with the same name run in the same executor, one at a time; the first call with a new name creates it. Calls on different executors run concurrently. 'default' names the executor that runs calls without a name. example: checkout pattern: ^[A-Za-z0-9_-]{1,64}$ type: string PlaywrightTab: additionalProperties: false description: >- The tab 'page' was bound to for this call. Absent if the call failed before binding a tab. properties: created: description: > Whether this call opened the tab. For a named executor this happens on its first call and after its previous tab was closed. For the default executor it happens only when the browser had no open page. type: boolean target_id: description: CDP page target ID of the tab type: string required: - target_id - created type: object Error: properties: code: description: Application-specific error code (machine-readable) example: bad_request type: string details: description: Additional error details (for multiple errors) items: $ref: '#/components/schemas/ErrorDetail' type: array inner_error: $ref: '#/components/schemas/ErrorDetail' message: description: Human-readable error description for debugging example: 'Missing required field: app_name' type: string required: - code - message type: object PlaywrightExecutor: additionalProperties: false description: A Playwright executor on the browser properties: busy: description: Whether a call is running on the executor type: boolean created_at: description: When the executor was created format: date-time type: string last_used_at: description: When the most recent call on the executor started format: date-time type: string name: $ref: '#/components/schemas/PlaywrightExecutorName' target_id: description: >- CDP page target ID of the executor's tab, once it has one. The default executor owns no tab. type: string url: description: Current URL of the executor's tab, when it is open type: string required: - name - busy - created_at - last_used_at type: object InstanceProxyError: properties: code: $ref: '#/components/schemas/InstanceProxyErrorCode' message: description: Human-readable error description for debugging type: string required: - code - message type: object ErrorDetail: properties: code: description: Lower-level error code providing more specific detail example: invalid_input type: string message: description: Further detail about the error example: Provided version string is not semver compliant type: string type: object InstanceProxyErrorCode: description: Canonical error code returned by browser instance API proxy routes enum: - invalid_request - unauthorized - forbidden - session_not_leased - not_found - conflict - session_gone - rate_limit_exceeded - internal_error - browser_unavailable type: string responses: BadRequest: content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad Request – invalid input InternalError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error BrowserProxyError: content: application/json: schema: $ref: '#/components/schemas/InstanceProxyError' description: Error returned by the browser or its proxy securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.