Repository navigation
Document browser memory tiers and page crash recovery - #700
Conversation
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
left a comment
hiroTamada
left a comment
There was a problem hiding this comment.
reviewed — useful sizing and retry-safety guidance, with three accuracy fixes:
- [P1]
browsers/concurrency-and-limits.mdx:54–60— headless now supports1GiB(default),2GiB, and4GiB, per the live API spec (https://api.onkernel.com/spec.json). update the fixed-ceiling claims inbrowsers/headless.mdx:7,introduction/configure.mdx:65,86, andintroduction/create.mdx:77, plus the headful-only recovery recommendation inbrowsers/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—sessionStoragecan survive a renderer crash and navigation in the same tab. distinguish recovering the existing tab from creating a replacement tab, which has separate storage.
…tier-and-page-crash # Conflicts: # browsers/concurrency-and-limits.mdx # browsers/headless.mdx
This branch was successfully deployed
2 participants
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.mdxnow 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: runfree -minside the session and watchavailable. 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, andintroduction/create.mdxwere 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.mdxgets 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
Notes for review
AGENTS.mdgoverns style here, and it overrides the lowercase brand rule. These edits follow the repo: sentence case headings, second person, no "should", no "please".<Card>(introduction/create.mdx) reaches agent consumers as a component tag rather than prose, becausellms-full.txtand the per-page.mdroutes serve the raw MDX. The canonical statement is in plain prose inconcurrency-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 devand 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 updates; no runtime, API, or auth changes.
Overview
Documentation expands browser memory tiers and ties OOM to
Page crashed/Target crashed.concurrency-and-limitsnow lists headful 8 GB or 16 GB and headless 1 / 2 / 4 GB, states memory is fixed at create (including pool updates applying only to new browsers), links crashes to kernel OOM kills, and addsfree -mplus scaling guidance instead of the old “many tabs” framing.Introduction and headless pages now surface those tiers when choosing headful vs headless, and headless warns that a single heavy page can exhaust the 1 GB default.
Playwright execution adds “A crashed page”: what the errors mean, what browser state survives vs tab state, recovery (re-navigate; named executors open a new tab), idempotency checks before retrying writes, and telemetry (
system_oom_kill) for recurring crashes.Reviewed by Cursor Bugbot for commit 426374d. Bugbot is set up for automated code reviews on this repo. Configure here.