Document browser memory tiers and page crash recovery

[robertjamesprior]

Summary

Two gaps in the browser docs, both of which surface to a user as a page failing with Page crashed.

Memory tiers were a footnote, but they're the constraint that decides whether a workload works. browsers/concurrency-and-limits.mdx now states the tiers (headful 8 GB or 16 GB, headless fixed at 1 GB), that memory is chosen at creation and can't be changed on a running browser, and that a headless browser has no larger tier to move to, so the only route to more memory is recreating it headful. It also inlines the check: run free -m inside the session and watch available. The previous copy said "open a dozen heavy tabs in one and Chromium starts killing renderers", which sets the bar far too high. browsers/headless.mdx, introduction/configure.mdx, and introduction/create.mdx were steering readers toward headless for "simple scraping" and "short-lived or highly concurrent" work without mentioning the 1 GB ceiling, which is the configuration where this fails.

There was no explanation of, or recovery path for, a crashed page. browsers/playwright-execution.mdx gets a new "A crashed page" subsection: what the error means, what survives (cookies, local storage, the logged-in session) and what doesn't (JavaScript state, sessionStorage, in-flight requests), how to recover, and the fact that a crash doesn't tell you whether the step you were running took effect, so writing actions need a result check before they're resent.

Deliberately not covered

• The pool behavior where a released browser can carry a crashed tab back into the pool. That needs a product fix before it becomes documented behavior.
• Whether the default (pinned) executor rebinds to a crashed tab or keeps returning the dead one. The named-executor path is documented because it's verified; the default path is left silent rather than guessed.
• A standalone troubleshooting page. Worth doing once the failure is surfaced in session details, rather than documenting a workaround for a signal users can't currently see.

Notes for review

• The docs repo's own AGENTS.md governs style here, and it overrides the lowercase brand rule. These edits follow the repo: sentence case headings, second person, no "should", no "please".
• The one sentence that sits inside a <Card> (introduction/create.mdx) reaches agent consumers as a component tag rather than prose, because llms-full.txt and the per-page .md routes serve the raw MDX. The canonical statement is in plain prose in concurrency-and-limits.mdx, so the card is an echo, but that sentence would read better in the body text below the card grid.

Verification

Ran mintlify dev and loaded every edited page (HTTP 200); confirmed the new anchor targets resolve on the rendered pages. The memory enum, the create-only constraint, and the named-executor tab-replacement behavior were checked against the current API contract and the in-VM executor implementation instead of being inferred from existing docs.

---

Note

Low Risk
Documentation-only changes with no runtime or API behavior modifications.

Overview
This PR expands browser docs around memory limits and Page crashed / Target crashed so readers understand why pages fail and how to recover.

Per-browser resources (concurrency-and-limits.mdx) now spells out headful 8 GB or 16 GB vs headless fixed 1 GB, that memory is chosen at create (and pool updates only affect new browsers), and that OOM can kill a single heavy tab—not just “many tabs.” It adds practical checks (free -m) and links to crash recovery and process metrics.

Headless and getting-started pages (headless.mdx, configure.mdx, create.mdx) no longer steer users toward headless for heavy work without calling out the 1 GB ceiling; configure adds memory: "8GiB" / "16GiB" for headful.

Playwright execution gains an “A crashed page” section: what the errors mean, what persists (cookies, local storage, session) vs what’s lost, navigate-to-recover, named-executor tab replacement, idempotent retries for write actions, and using telemetry (system_oom_kill) when crashes repeat.

^{Reviewed by Cursor Bugbot for commit 5aa17ec. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Kernel	🟢 Ready	View Preview	Oct 14, 2026, 2:38 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 5aa17ec. Configure here.}

[cursor]

Relative API reference create link

Medium Severity

The new memory guidance links to create-a-browser-session with a relative /api-reference/... path. Those pages are generated from the remote OpenAPI spec and are not local MDX, so relative links fail mint broken-links and 404 in-repo. Absolute https://www.kernel.sh/docs/api-reference/... URLs are the working form.

 

^{Triggered by learned rule: Use absolute URLs for /api-reference/ links}

^{Reviewed by Cursor Bugbot for commit 5aa17ec. Configure here.}

[hiroTamada]

reviewed — useful sizing and retry-safety guidance, with three accuracy fixes:

• [P1] browsers/concurrency-and-limits.mdx:54–60 — headless now supports 1GiB (default), 2GiB, and 4GiB, per the live API spec (https://api.onkernel.com/spec.json). update the fixed-ceiling claims in browsers/headless.mdx:7, introduction/configure.mdx:65,86, and introduction/create.mdx:77, plus the headful-only recovery recommendation in browsers/playwright-execution.mdx:439.
• [P2] browsers/playwright-execution.mdx:429 — a renderer crash doesn't establish OOM or mean the tab disappeared. describe OOM as a possible cause and confirm it through telemetry before recommending more memory.
• [P2] browsers/playwright-execution.mdx:431 — sessionStorage can survive a renderer crash and navigation in the same tab. distinguish recovering the existing tab from creating a replacement tab, which has separate storage.