---
title: "Execute JavaScript in the persistent Browser REPL"
method: POST
path: "/browsers/{id_or_name}/repl"
tags: ["Browser REPL"]
---

# Execute JavaScript in the persistent Browser REPL

`POST /browsers/{id_or_name}/repl`

## Request

- Base URL: `https://api.onkernel.com`
- URL: `https://api.onkernel.com/browsers/{id_or_name}/repl`
- Auth: HTTP bearer

Execute JavaScript in a persistent Node.js runtime inside the browser VM.
Top-level bindings, closures, mutations, and dynamically imported modules persist
across calls until the REPL is reset or replaced. Start with `repl.help()` to list
available methods, or call `repl.help("click")` for detailed help.

Expression values are ignored. Emit ordered text or image output with
`repl.write(...)`, console methods, or `repl.emitImage(...)`. The runtime also
exposes browser-control helpers, WebMCP, Patchright, Playwright, and raw CDP.

Executions are serialized. A timeout, crash, OOM, or protocol failure terminates
the REPL and changes its `repl_id`. This is unrestricted code execution inside the
browser VM and is not sandboxed.

## Path parameters

- `id_or_name` string, required

## Headers

- `Idempotency-Key` string

## Request body

- BrowserReplRequest: Request to execute code in the persistent Browser REPL.
  - `code` string, required: JavaScript evaluated in a persistent Node.js runtime. Top-level bindings persist until the browser VM's API process exits, the REPL is reset, or the REPL is terminated after a crash or timeout. Static top-level imports are unsupported; use dynamic `import()`. Expression values are ignored; emit output with `repl.write(...)`, console methods, or `repl.emitImage(...)`. May be empty only when `reset` is true.
  - `reset` boolean: Terminate the current REPL, start a fresh one, and then evaluate code.
  - `timeout_sec` integer: Maximum execution time in seconds. Default is 60.

## Response `200`

Code executed with either a successful result or a structured JavaScript failure.

- BrowserReplResult: Result of Browser REPL code execution.
  - `content` BrowserReplContent[]: Optional ordered text/image output produced by the execution.
    - union: Ordered discriminated union of Browser REPL output items.
      - BrowserReplTextContent
        - `channel` 'write' | 'stdout' | 'stderr', required: `write` is emitted by `repl.write`; `stdout` and `stderr` are emitted by console methods.
        - `text` string, required
        - `type` 'text', required
      - BrowserReplImageContent
        - `data_b64` string, byte, required
        - `mime_type` string, required
        - `type` 'image', required
  - `content_truncated` boolean: True if text or image output was dropped or truncated due to response limits.
  - `duration_ms` integer: Wall-clock execution time in milliseconds.
  - `error` string: Error message if execution failed.
  - `repl_id` string, required: CUID2 identifying the exact state-holding REPL process used for this execution. Stable across calls and Chromium reconnects; changes after an API restart, explicit reset, execution timeout, or REPL crash.
  - `repl_terminated` boolean: True if the REPL identified by `repl_id` was terminated by this request. The next request lazily starts a fresh REPL with a new `repl_id`.
  - `stack` string: Stack trace if execution failed.
  - `success` boolean, required: Whether the code executed successfully.

## Other responses

- `400`: Bad Request – invalid input
- `413`: Bad Request – invalid input
- `422`: The Idempotency-Key was already used for a request with different parameters
- `500`: Internal Server Error
- `default`: Error returned by the browser or its proxy

## Changes

- **2026-10-28** `5e31244c396e`: 2 info
  - added the new optional `header` request parameter `Idempotency-Key`
  - added the non-success response with the status `422`
- **2026-10-16** `03b369edee49`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kernel/apis/kernel-api/changes/browsers/:id_or_name/repl/post.md)

---

[API](https://skmtc.dev/kernel/apis/kernel-api.md) - [All operations](https://skmtc.dev/kernel/apis/kernel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kernel/apis/kernel-api/revisions/0f6cf4f58fe6?raw)