diff --git a/browsers/concurrency-and-limits.mdx b/browsers/concurrency-and-limits.mdx index 536f498a..999facf3 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, 2 GB, or 4 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. non-gpu browsers support `2GiB` or `4GiB` headless, or `16GiB` headful: set `memory` when you [create a browser](https://www.kernel.sh/docs/api-reference/browsers/create-a-browser-session) or [browser pool](/browsers/pools) for workloads that need more than the default. +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). + +Memory is set when the browser is created and can't be changed on a running browser: headless browsers take `1GiB`, `2GiB`, or `4GiB`, and headful browsers take `8GiB` (the default) or `16GiB`. Pass `memory` to [create](/api-reference/browsers/create-a-browser-session) or set it on a [browser pool](/browsers/pools); a pool change applies only to browsers built after it. + +If pages are dying, create the browser 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/headless.mdx b/browsers/headless.mdx index fcd2b7d9..0591a3a7 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 by default 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. They generally run faster and have a lighter footprint (1 GB by default rather than headful's 8 GB), resulting in significant cost savings. This is useful for short-lived or highly concurrent browser automations, but a single heavy page can exhaust the 1 GB default, so [size the browser to the page](/browsers/concurrency-and-limits#per-browser-resources) rather than assuming headless only suits light work. Some bot detectors may detect headless mode. for more memory on a non-gpu browser, set `memory` to `2GiB` or `4GiB` when you [create a headless browser](https://www.kernel.sh/docs/api-reference/browsers/create-a-browser-session) or [headless browser pool](/browsers/pools). the default remains `1GiB`. diff --git a/browsers/playwright-execution.mdx b/browsers/playwright-execution.mdx index f39a3866..3b04f195 100644 --- a/browsers/playwright-execution.mdx +++ b/browsers/playwright-execution.mdx @@ -424,6 +424,20 @@ 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 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. 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 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. + ## 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..c2498753 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. 1 GB by default, or 2 GB and 4 GB with `memory`; 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):** headless browsers take `1GiB`, `2GiB`, or `4GiB`; headful browsers take `8GiB` (the default) or `16GiB`. 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..e210da28 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, from 1 GB up to 4 GB, which suits high-volume work. Turn on stealth mode and route through residential or ISP proxies when you're hitting sites with bot detection.