KEkernel
Browsers

Create a browser session

Changed on

Create a new browser session from within an action.

post/browsers

Request

  • Base URL
    https://api.onkernel.com
  • URL
    https://api.onkernel.com/browsers
  • Auth
    HTTP bearer

Request body

chrome_policyobject

Custom Chrome enterprise policy overrides applied to this browser session. Keys are Chrome enterprise policy names; values must match their expected types. Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See https://chromeenterprise.google/policies/

gpuboolean

If true, enables GPU acceleration for the browser session. Requires Start-Up or Enterprise plan, headless=false, and region=us-east.

headlessboolean

If true, launches the browser using a headless image (no VNC/GUI). Defaults to false.

invocation_idstring

action invocation ID

kiosk_modeboolean

If true, launches the browser in kiosk mode to hide address bar and tabs in live view.

memory'1GiB' | '2GiB' | '4GiB' | '8GiB' | '16GiB'

Memory requested for a non-GPU browser. Headless browsers support 1GiB (default), 2GiB, or 4GiB; headful browsers support 8GiB (default) or 16GiB.

namestring

Optional human-readable name for the browser session, used to find it later in the dashboard. Must be unique among active sessions within the project. Can be changed later via PATCH /browsers/{id_or_name}.

proxy_idstring

Optional proxy to associate to the browser session. Must reference a proxy in the same project as the browser session. Deprecated in favor of proxy.

region'us-east' | 'us-west' | 'eu-west' | 'ap-southeast'

Geographic region for hosting browser sessions or pools.

start_urlstring

Optional URL to open when the browser session is created. Navigation is best-effort, so navigation failures do not prevent the session from being created.

stealthboolean

If true, launches the browser in stealth mode and enables the CAPTCHA solver. Defaults to false. When proxy is omitted, stealth browsers use Kernel's default stealth proxy and non-stealth browsers use direct egress. An explicit proxy configuration changes only egress; it does not enable or disable stealth or the CAPTCHA solver.

tagsTags

User-defined key-value tags.

timeout_secondsinteger

The number of seconds of inactivity before the browser session is terminated. Activity includes CDP connections and live view connections. Defaults to 60 seconds. Minimum allowed is 10 seconds. Maximum allowed is 259200 (72 hours). We check for inactivity every 5 seconds, so the actual timeout behavior you will see is +/- 5 seconds around the specified value.

video_memory'2GiB' | '4GiB'

Video memory (VRAM) of a GPU browser session. 2GiB sessions have 4 vCPU and 6GiB memory. 4GiB sessions have 8 vCPU and 12GiB memory.

Example request

{
  "fingerprint": {
    "os": "macos"
  },
  "invocation_id": "rr33xuugxj9h0bkf1rdt2bet",
  "kiosk_mode": true,
  "location": {
    "locale": "en-US",
    "timezone": "America/Los_Angeles"
  },
  "memory": "8GiB",
  "name": "checkout-flow-1",
  "network": {
    "allowed_hosts": [
      "example.com",
      "*.example.com"
    ],
    "private_hosts": [
      "*.example.ts.net",
      "100.64.0.0/10"
    ]
  },
  "start_url": "https://example.com",
  "stealth": true,
  "tags": {
    "env": "staging",
    "team": "backend"
  },
  "video_memory": "2GiB",
  "viewport": {
    "height": 800,
    "refresh_rate": 60,
    "width": 1280
  }
}

Response

Successful response

base_urlstring

Metro-API HTTP base URL for this browser session.

browser_live_view_urlstring

Remote URL for live viewing the browser session. Only available for non-headless browsers.

cdp_ws_urlstring required

Websocket URL for Chrome DevTools Protocol connections to the browser session

chrome_policyobject

Custom Chrome enterprise policy overrides that were applied to this browser session, if any. Echoed back for verification. Keys are Chrome enterprise policy names.

created_atstring date-time required

When the browser session was created.

deleted_atstring date-time

When the browser session was soft-deleted. Only present for deleted sessions.

gpuboolean

Whether GPU acceleration is enabled for the browser session (only supported for headful sessions).

headlessboolean required

Whether the browser session is running in headless mode.

kiosk_modeboolean

Whether the browser session is running in kiosk mode.

leased_atstring date-time

When the pooled browser session was last leased. Only present for leased pooled sessions.

memory'1GiB' | '2GiB' | '4GiB' | '6GiB' | '8GiB' | '12GiB' | '16GiB' required

Memory allocated to the browser session.

namestring

Human-readable name of the browser session, if one was set at creation.

profile_save_changesboolean

Whether changes made during this browser session are saved back to its profile when the session ends. Omitted when no profile is attached.

proxy_idstring

ID of the proxy associated with this browser session, if any. Deprecated in favor of proxy.

region'us-east' | 'us-west' | 'eu-west' | 'ap-southeast' required

Geographic region for hosting browser sessions or pools.

session_idstring required

Unique identifier for the browser session

start_urlstring

URL the session was most recently asked to navigate to, if any. Recorded for debugging. Navigation is fire-and-forget — the URL is dispatched to the browser without waiting for it to load, and any errors (DNS failure, bad status, timeout) are silently dropped. Captures what was requested, not what the browser actually loaded.

stealthboolean required

Whether the browser session is running in stealth mode.

tagsTags

User-defined key-value tags.

timeout_secondsinteger required

The number of seconds of inactivity before the browser session is terminated.

usage_status'pending' | 'ready'

Whether final usage billing is still pending or complete. Only present for deleted sessions.

video_memory'2GiB' | '4GiB'

Video memory (VRAM) of a GPU browser session. 2GiB sessions have 4 vCPU and 6GiB memory. 4GiB sessions have 8 vCPU and 12GiB memory.

webdriver_ws_urlstring required

Websocket URL for WebDriver BiDi connections to the browser session

Example response

{
  "base_url": "https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/kernel",
  "browser_live_view_url": "https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/live?jwt=eyJ0eXAi...",
  "cdp_ws_url": "wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/cdp?jwt=eyJ0eXAi...",
  "location": {
    "locale": "en-US",
    "timezone": "America/Los_Angeles"
  },
  "memory": "8GiB",
  "name": "checkout-flow-1",
  "network": {
    "allowed_hosts": [
      "example.com",
      "*.example.com"
    ],
    "private_hosts": [
      "*.example.ts.net",
      "100.64.0.0/10"
    ]
  },
  "session_id": "htzv5orfit78e1m2biiifpbv",
  "start_url": "https://example.com",
  "tags": {
    "env": "staging",
    "team": "backend"
  },
  "video_memory": "2GiB",
  "viewport": {
    "height": 800,
    "refresh_rate": 60,
    "width": 1280
  },
  "webdriver_ws_url": "wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/webdriver/session?jwt=eyJ0eXAi..."
}

Changes