From 03df0a8471a198a4f01c063a0eaa6ddba5bd1ee5 Mon Sep 17 00:00:00 2001 From: robertjamesprior <83608739+robertjamesprior@users.noreply.github.com> Date: Tue, 13 Oct 2026 23:20:55 +0000 Subject: [PATCH 1/3] Document browser memory tiers and page crash recovery --- browsers/concurrency-and-limits.mdx | 8 ++++++-- browsers/headless.mdx | 2 +- browsers/playwright-execution.mdx | 10 ++++++++++ introduction/configure.mdx | 5 +++-- introduction/create.mdx | 2 +- 5 files changed, 21 insertions(+), 6 deletions(-) diff --git a/browsers/concurrency-and-limits.mdx b/browsers/concurrency-and-limits.mdx index d83c71b0..d5d2df1f 100644 --- a/browsers/concurrency-and-limits.mdx +++ b/browsers/concurrency-and-limits.mdx @@ -51,9 +51,13 @@ If you're hitting the ceiling in normal operation, [contact us](https://calendly | Resource | Headful | Headless | | --- | --- | --- | -| Default memory | 8 GB | 1 GB | +| Memory | 8 GB or 16 GB | 1 GB | -Memory is the practical ceiling on how many tabs and how heavy a page one browser handles. A [headless](/browsers/headless) browser at 1 GB is sized for short-lived, single-page, high-concurrency automation; open a dozen heavy tabs in one and Chromium starts killing renderers. If your workload needs many concurrent pages, spread it across more browsers rather than more tabs in one. Headful browsers support up to 16 GB: set `memory` on a [browser pool](/browsers/pools) when a workload needs more than the default. +Memory is the practical ceiling on how heavy a page one browser can hold. When a browser runs past its tier, the kernel kills a Chromium process and the page fails with `Page crashed` or `Target crashed`. One heavy page can do this on its own — it doesn't take many tabs. See [a crashed page](/browsers/playwright-execution#a-crashed-page). + +A headless browser always has 1 GB, and you can't raise it. A headful browser gets 8 GB by default and 16 GB when you pass `memory` to [create](/api-reference/browsers/create-a-browser-session) or set it on a [browser pool](/browsers/pools). Memory is chosen at creation and can't be changed on a running browser; a pool change applies only to browsers built after it. + +If pages are dying, step up a tier or spread the work across more browsers rather than more tabs in one. To size a workload before it fails, [read the browser's memory from inside the session](/browsers/process-execution#measure-memory-and-cpu-usage). [GPU acceleration](/browsers/gpu-acceleration) is a separate browser type with its own [usage rate](/info/pricing#usage-rates), available on Start-Up and Enterprise. diff --git a/browsers/headless.mdx b/browsers/headless.mdx index b2bb1d94..2816360d 100644 --- a/browsers/headless.mdx +++ b/browsers/headless.mdx @@ -4,7 +4,7 @@ title: "Headless Mode" Kernel browsers ship in `headful` mode by default. In headful mode, the launched browser has a corresponding GUI. This enables features like [live view](/browsers/live-view) and [replays](/browsers/replays). -`headless` mode runs without a visual interface. They generally run faster and have a lighter footprint (1 GB rather than headful's 8 GB), resulting in significant cost savings. This is useful for short-lived or highly concurrent browser automations. +`headless` mode runs without a visual interface. Headless browsers start faster and use 1 GB of memory instead of headful's 8 GB, which makes them cheaper for high-volume work. That 1 GB is fixed: you can't raise it, so a memory-heavy page that runs fine in a headful browser can exhaust a headless one. See [per-browser resources](/browsers/concurrency-and-limits#per-browser-resources). Some bot detectors may detect headless mode. To launch a Kernel browser in `headless` mode, set its config: diff --git a/browsers/playwright-execution.mdx b/browsers/playwright-execution.mdx index f39a3866..cafa1759 100644 --- a/browsers/playwright-execution.mdx +++ b/browsers/playwright-execution.mdx @@ -424,6 +424,16 @@ Deleting `default` restarts it instead of removing it: its process is stopped, a 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. +### A crashed page + +`Page crashed` and `Target crashed` mean the tab is gone. The browser ran past its [memory tier](/browsers/concurrency-and-limits#per-browser-resources) and the kernel killed a Chromium process. The error names the page rather than the cause. + +The browser survives, and so do its cookies, local storage, and logged-in sessions, because those belong to the browser rather than the tab. What's lost is everything the page held in memory: JavaScript state, `sessionStorage`, and any request in flight. + +Recover by navigating again. A named executor whose tab has been closed gets a replacement tab and the call is sent again on it, so code that assumes a page position, a populated form, or an open dialog must navigate and wait for the page before continuing. + +If the crashes recur, step up a memory tier or spread the work across more browsers. To confirm the cause, enable [telemetry](/browsers/telemetry/overview); the default set includes the `system` category, whose [`system_oom_kill`](/browsers/telemetry/categories) event reports the killed process's memory. + ## 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: diff --git a/introduction/configure.mdx b/introduction/configure.mdx index c0b41925..bab136d0 100644 --- a/introduction/configure.mdx +++ b/introduction/configure.mdx @@ -61,8 +61,8 @@ The response includes everything you need to drive the browser: `session_id`, `c | Type | When to use it | How to set it | | --- | --- | --- | -| **Headful** (default) | Agents on real sites. It has a real display, so [live view](/browsers/live-view) and [replays](/browsers/replays) work and bot detectors see a normal browser. 8 GB of memory by default. | Nothing to set | -| **[Headless](/browsers/headless)** | Short-lived or highly concurrent jobs that don't need to be watched. Lighter, at 1 GB by default, but some bot detectors notice it. | `headless: true` | +| **Headful** (default) | Agents on real sites. It has a real display, so [live view](/browsers/live-view) and [replays](/browsers/replays) work and bot detectors see a normal browser. 8 GB of memory by default, or 16 GB with `memory`. | `memory: "8GiB"` or `"16GiB"` | +| **[Headless](/browsers/headless)** | High-volume or short-lived work that doesn't need to be watched. Fixed at 1 GB, so keep individual pages light; some bot detectors notice it. | `headless: true` | | **[GPU-accelerated](/browsers/gpu-acceleration)** | WebGL, video, and canvas-heavy sites. Headful only, doesn't support standby, and has its own usage rate. | `gpu: true` | ## Set common options @@ -83,6 +83,7 @@ browser = kernel.browsers.create( ``` +- **[Memory](/browsers/concurrency-and-limits#per-browser-resources):** headful browsers take `8GiB` (the default) or `16GiB`. Headless browsers are fixed at `1GiB`. Memory is set at creation and can't be changed on a running browser. - **[Viewport](/browsers/viewport):** defaults to 1920x1080 at 25Hz. A custom viewport restarts Chromium on creation, so use a [browser pool](/browsers/pools) if you need it to be instant. - **[Termination and timeouts](/browsers/termination):** `timeout_seconds` sets how long a browser can sit in standby before KERNEL deletes it. It defaults to 60 seconds and can be up to 72 hours. Delete browsers explicitly when you're done; Playwright's `browser.close()` doesn't delete them. diff --git a/introduction/create.mdx b/introduction/create.mdx index 99c9bfba..67ccd821 100644 --- a/introduction/create.mdx +++ b/introduction/create.mdx @@ -74,7 +74,7 @@ Most of what you'll tune at creation time falls into four buckets: - headful (default) supports live view, replays, and better stealth — ideal for agent workflows on bot-detected sites. headless is lighter (1 gb vs 8 gb), good for simple scraping. + Headful (default) supports live view, replays, and better stealth, and takes 8 GB or 16 GB of memory. Headless is lighter, at a fixed 1 GB, which suits high-volume work with light pages. Turn on stealth mode and route through residential or ISP proxies when you're hitting sites with bot detection. From 71fcb5b441246f677e171e80aeff76c7d098640d Mon Sep 17 00:00:00 2001 From: robertjamesprior <83608739+robertjamesprior@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:33:33 +0000 Subject: [PATCH 2/3] Make the headless memory ceiling and crash recovery actionable --- browsers/concurrency-and-limits.mdx | 4 ++-- browsers/playwright-execution.mdx | 4 +++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/browsers/concurrency-and-limits.mdx b/browsers/concurrency-and-limits.mdx index d5d2df1f..f3134c10 100644 --- a/browsers/concurrency-and-limits.mdx +++ b/browsers/concurrency-and-limits.mdx @@ -55,9 +55,9 @@ If you're hitting the ceiling in normal operation, [contact us](https://calendly Memory is the practical ceiling on how heavy a page one browser can hold. When a browser runs past its tier, the kernel kills a Chromium process and the page fails with `Page crashed` or `Target crashed`. One heavy page can do this on its own — it doesn't take many tabs. See [a crashed page](/browsers/playwright-execution#a-crashed-page). -A headless browser always has 1 GB, and you can't raise it. A headful browser gets 8 GB by default and 16 GB when you pass `memory` to [create](/api-reference/browsers/create-a-browser-session) or set it on a [browser pool](/browsers/pools). Memory is chosen at creation and can't be changed on a running browser; a pool change applies only to browsers built after it. +A headless browser always has 1 GB and no larger tier to move to. A headful browser gets 8 GB by default and 16 GB when you pass `memory` to [create](/api-reference/browsers/create-a-browser-session) or set it on a [browser pool](/browsers/pools). Memory is chosen at creation and can't be changed on a running browser; a pool change applies only to browsers built after it. -If pages are dying, step up a tier or spread the work across more browsers rather than more tabs in one. To size a workload before it fails, [read the browser's memory from inside the session](/browsers/process-execution#measure-memory-and-cpu-usage). +If pages are dying, recreate the browser headful with more memory, or spread the work across more browsers rather than more tabs in one. To check whether memory is the cause before a page fails, run `free -m` inside the session and watch `available`: if it trends toward zero first, the page's working set is the problem. See [measure memory and CPU usage](/browsers/process-execution#measure-memory-and-cpu-usage). [GPU acceleration](/browsers/gpu-acceleration) is a separate browser type with its own [usage rate](/info/pricing#usage-rates), available on Start-Up and Enterprise. diff --git a/browsers/playwright-execution.mdx b/browsers/playwright-execution.mdx index cafa1759..60ad16b4 100644 --- a/browsers/playwright-execution.mdx +++ b/browsers/playwright-execution.mdx @@ -432,7 +432,9 @@ The browser survives, and so do its cookies, local storage, and logged-in sessio Recover by navigating again. A named executor whose tab has been closed gets a replacement tab and the call is sent again on it, so code that assumes a page position, a populated form, or an open dialog must navigate and wait for the page before continuing. -If the crashes recur, step up a memory tier or spread the work across more browsers. To confirm the cause, enable [telemetry](/browsers/telemetry/overview); the default set includes the `system` category, whose [`system_oom_kill`](/browsers/telemetry/categories) event reports the killed process's memory. +A crash also doesn't tell you whether the step you were running took effect. Before you resend an action that writes something, check the page or the downstream system for the expected result rather than retrying on the assumption that nothing happened. Follow the [unknown-outcome guidance](/browsers/webmcp#handle-an-unknown-outcome). + +If the crashes recur, recreate the browser headful with more memory or spread the work across more browsers. To confirm the cause, enable [telemetry](/browsers/telemetry/overview); the default set includes the `system` category, whose [`system_oom_kill`](/browsers/telemetry/categories) event reports the killed process's memory. ## Timeout configuration From 5aa17ecea35b1db8744dbac633d97786f3f439e9 Mon Sep 17 00:00:00 2001 From: robertjamesprior <83608739+robertjamesprior@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:36:47 +0000 Subject: [PATCH 3/3] Read through the new memory and crash guidance for clarity --- browsers/concurrency-and-limits.mdx | 6 +++--- browsers/playwright-execution.mdx | 8 +++++--- introduction/configure.mdx | 2 +- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/browsers/concurrency-and-limits.mdx b/browsers/concurrency-and-limits.mdx index f3134c10..cac392ff 100644 --- a/browsers/concurrency-and-limits.mdx +++ b/browsers/concurrency-and-limits.mdx @@ -53,11 +53,11 @@ If you're hitting the ceiling in normal operation, [contact us](https://calendly | --- | --- | --- | | Memory | 8 GB or 16 GB | 1 GB | -Memory is the practical ceiling on how heavy a page one browser can hold. When a browser runs past its tier, the kernel kills a Chromium process and the page fails with `Page crashed` or `Target crashed`. One heavy page can do this on its own — it doesn't take many tabs. See [a crashed page](/browsers/playwright-execution#a-crashed-page). +Memory is the practical ceiling on how heavy a page one browser can hold. When a browser runs out of memory, the kernel kills a Chromium process and the page fails with `Page crashed` or `Target crashed`. One heavy page can do this on its own — it doesn't take many tabs. See [a crashed page](/browsers/playwright-execution#a-crashed-page). -A headless browser always has 1 GB and no larger tier to move to. A headful browser gets 8 GB by default and 16 GB when you pass `memory` to [create](/api-reference/browsers/create-a-browser-session) or set it on a [browser pool](/browsers/pools). Memory is chosen at creation and can't be changed on a running browser; a pool change applies only to browsers built after it. +Headless browsers have 1 GB and no larger option. Headful browsers get 8 GB by default and 16 GB when you pass `memory` to [create](/api-reference/browsers/create-a-browser-session) or set it on a [browser pool](/browsers/pools). Memory is fixed at creation: you can't change it on a running browser, and a pool change applies only to browsers built after it. -If pages are dying, recreate the browser headful with more memory, or spread the work across more browsers rather than more tabs in one. To check whether memory is the cause before a page fails, run `free -m` inside the session and watch `available`: if it trends toward zero first, the page's working set is the problem. See [measure memory and CPU usage](/browsers/process-execution#measure-memory-and-cpu-usage). +If pages are dying, recreate the browser headful with more memory, or spread the work across more browsers rather than more tabs in one. To check memory before a page fails, run `free -m` inside the session and watch `available`. If it trends toward zero before the page dies, the page's working set is the problem. See [measure memory and CPU usage](/browsers/process-execution#measure-memory-and-cpu-usage). [GPU acceleration](/browsers/gpu-acceleration) is a separate browser type with its own [usage rate](/info/pricing#usage-rates), available on Start-Up and Enterprise. diff --git a/browsers/playwright-execution.mdx b/browsers/playwright-execution.mdx index 60ad16b4..3b04f195 100644 --- a/browsers/playwright-execution.mdx +++ b/browsers/playwright-execution.mdx @@ -426,13 +426,15 @@ After a timeout, the executor keeps its process but drops its browser connection ### A crashed page -`Page crashed` and `Target crashed` mean the tab is gone. The browser ran past its [memory tier](/browsers/concurrency-and-limits#per-browser-resources) and the kernel killed a Chromium process. The error names the page rather than the cause. +`Page crashed` and `Target crashed` mean the tab is gone. The browser [ran out of memory](/browsers/concurrency-and-limits#per-browser-resources) and the kernel killed a Chromium process. The error names the page rather than the cause. The browser survives, and so do its cookies, local storage, and logged-in sessions, because those belong to the browser rather than the tab. What's lost is everything the page held in memory: JavaScript state, `sessionStorage`, and any request in flight. -Recover by navigating again. A named executor whose tab has been closed gets a replacement tab and the call is sent again on it, so code that assumes a page position, a populated form, or an open dialog must navigate and wait for the page before continuing. +Recover by navigating again. Nothing about the page's position survives, so code that assumes a populated form, an open dialog, or a specific page must navigate and wait before continuing. -A crash also doesn't tell you whether the step you were running took effect. Before you resend an action that writes something, check the page or the downstream system for the expected result rather than retrying on the assumption that nothing happened. Follow the [unknown-outcome guidance](/browsers/webmcp#handle-an-unknown-outcome). +A named executor replaces a missing tab: if its tab is gone, the call is sent again on a new one. + +A crash doesn't tell you whether the step you were running took effect. Before you resend an action that writes something, check the page or the downstream system for the expected result. Follow the [unknown-outcome guidance](/browsers/webmcp#handle-an-unknown-outcome). If the crashes recur, recreate the browser headful with more memory or spread the work across more browsers. To confirm the cause, enable [telemetry](/browsers/telemetry/overview); the default set includes the `system` category, whose [`system_oom_kill`](/browsers/telemetry/categories) event reports the killed process's memory. diff --git a/introduction/configure.mdx b/introduction/configure.mdx index bab136d0..4244673d 100644 --- a/introduction/configure.mdx +++ b/introduction/configure.mdx @@ -62,7 +62,7 @@ The response includes everything you need to drive the browser: `session_id`, `c | Type | When to use it | How to set it | | --- | --- | --- | | **Headful** (default) | Agents on real sites. It has a real display, so [live view](/browsers/live-view) and [replays](/browsers/replays) work and bot detectors see a normal browser. 8 GB of memory by default, or 16 GB with `memory`. | `memory: "8GiB"` or `"16GiB"` | -| **[Headless](/browsers/headless)** | High-volume or short-lived work that doesn't need to be watched. Fixed at 1 GB, so keep individual pages light; some bot detectors notice it. | `headless: true` | +| **[Headless](/browsers/headless)** | High-volume or short-lived work that doesn't need to be watched. Fixed at 1 GB, so keep individual pages light. Some bot detectors notice it. | `headless: true` | | **[GPU-accelerated](/browsers/gpu-acceleration)** | WebGL, video, and canvas-heavy sites. Headful only, doesn't support standby, and has its own usage rate. | `gpu: true` | ## Set common options