From 2446bb718578deb17b22bbcabdd3d259b8c5a1fe Mon Sep 17 00:00:00 2001 From: Catherine Jue Date: Fri, 24 Apr 2026 11:02:43 -0700 Subject: [PATCH 1/3] add guidance on bpools --- browsers/pools/overview.mdx | 21 +++++++++++++++++++ ...{managing-browsers.mdx => policy-json.mdx} | 0 changelog.mdx | 2 +- docs.json | 2 +- 4 files changed, 23 insertions(+), 2 deletions(-) rename browsers/pools/{managing-browsers.mdx => policy-json.mdx} (100%) diff --git a/browsers/pools/overview.mdx b/browsers/pools/overview.mdx index 097b148..a80111e 100644 --- a/browsers/pools/overview.mdx +++ b/browsers/pools/overview.mdx @@ -5,6 +5,27 @@ description: "Pre-configure pools of reserved browsers for immediate acquisition Browser pools let you maintain a set of reserved, identical browsers ready for immediate use. Use them to set your preferred browser configuration in advance, allowing you to minimize browser start-up latency and scale your workloads in production. +## How browser pools work + +Browser pools are a way to pre-configure a fixed set of browsers without being charged for them until they are used (i.e. `acquired`). All browsers in the pool share the same settings upon instantiation. + + + + First, declare a pool of browsers with your specified configuration. The pool takes time to fill (see [fill rate per minute](https://www.kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-fill-rate-per-minute)), so declare your pool outside your browser automation / agent runtime logic. Pool declarations should be decoupled from browser use logic for the best performance. + + + You can acquire a browser as soon as you've created a pool. The request returns immediately if a browser is available, or waits until one becomes available. The `acquire_timeout_seconds` parameter controls how long to wait for a browser; it defaults to the calculated time it would take to fill the pool at the pool's configured [fill rate](https://www.kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-fill-rate-per-minute). + + The total number of usable browsers is fixed to the `size` specified upon browser pool creation. + + When you acquire a browser, the pool's available count is decremented by one. When you release a browser, the pool's available count is incremented by one. put differently, the pool does not top up when you acquire a browser: browsers are "borrowed" from the pool and must be returned when you're done with them, either by [releasing them](#release-a-browser) or allowing them to [timeout](#timeout-behavior). + + + When you're done with a browser, release it back to the pool. this step is important; otherwise, the browser will continue to be in an `acquired` state until it [times out](#timeout-behavior). Failing to release browsers may result in unexpected latency when acquiring future browsers if the pool is only refilling when browsers timeout. + + + + ## Create a pool of reserved browsers Create a browser pool with a specified size and configuration. All browsers in the pool share the same settings. diff --git a/browsers/pools/managing-browsers.mdx b/browsers/pools/policy-json.mdx similarity index 100% rename from browsers/pools/managing-browsers.mdx rename to browsers/pools/policy-json.mdx diff --git a/changelog.mdx b/changelog.mdx index 76ee6c5..0d0fb42 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -56,7 +56,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n ## Documentation updates - Documented MFA token auto-retry behavior for [managed auth](/auth/overview) sessions. -- Added a new [Managing Browsers](/browsers/pools/managing-browsers) page to the Reserved Browsers documentation. +- Added a new [policy.json](/browsers/pools/policy-json) page to the Reserved Browsers documentation. - Clarified that [profiles](/auth/profiles) can have multiple auth connections. - Added a Headful + GPU acceleration option to the [pricing calculator](/info/pricing#pricing-calculator). diff --git a/docs.json b/docs.json index b3a1a75..0f2a079 100644 --- a/docs.json +++ b/docs.json @@ -140,7 +140,7 @@ "group": "Reserved Browsers", "pages": [ "browsers/pools/overview", - "browsers/pools/managing-browsers", + "browsers/pools/policy-json", "browsers/pools/scaling", "browsers/pools/faq" ] From ef4f2b85aa22839e8ac405d9c45d85c58473ab63 Mon Sep 17 00:00:00 2001 From: Catherine Jue Date: Fri, 24 Apr 2026 11:42:33 -0700 Subject: [PATCH 2/3] add page about performance and latency, cuz we the best --- browsers/performance.mdx | 33 +++++++++++++++++++++++++++++++++ docs.json | 6 ++++++ 2 files changed, 39 insertions(+) create mode 100644 browsers/performance.mdx diff --git a/browsers/performance.mdx b/browsers/performance.mdx new file mode 100644 index 0000000..db4945b --- /dev/null +++ b/browsers/performance.mdx @@ -0,0 +1,33 @@ +--- +title: "Performance" +--- + +Kernel browsers [benchmark](https://www.kernel.sh/benchmarks) as the fastest, most performant browsers in the market. + +### Kernel browser creation latency +| Benchmark | Latency | Last reported | +|-----------|---------|---------------| +| P50 | 30ms | April 24, 2026 | +| P99 | 105ms | April 24, 2026 | + +### Troubleshooting latency +If you're experiencing slower-than-expected browser creation (or [browser pool acquisition](/browsers/pools/overview)), review your configuration for the following: + +1. App code ⇔ Kernel browser region + +Kernel browsers run in `us-east`. Use our [app platform](/apps/overview) to colocate your browser agent or automation. + +2. Create browser rate limit + +Kernel enforces [rate limits](/info/pricing#rate-limiting) on browser creation based on your plan. Our SDKs automatically retry, respecting the `Retry-After` header for delay timing. If retries are exhausted, the SDK throws a typed `RateLimitError` with the response headers accessible for custom backoff logic. + +3. Non-default browser configurations + +Certain browser configurations trigger Chromium to restart, which can take several seconds. Use [browser pools](/browsers/pools/overview) to access browsers with custom configurations faster. The following configurations cause browser restarts, as well as disrupt active CDP connections: +- Custom viewport configurations +- Chrome extensions +- Setting the live view to `kiosk mode` + +4. Browser pool refill rate + +Browser pools fill at a [specified rate](https://www.kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-fill-rate-per-minute). Read about browser pool lifecycle best practices [here](/browsers/pools/overview#how-browser-pools-work). \ No newline at end of file diff --git a/docs.json b/docs.json index 0f2a079..884a131 100644 --- a/docs.json +++ b/docs.json @@ -146,6 +146,12 @@ ] } ] + }, + { + "group": "FAQ", + "pages": [ + "browsers/performance" + ] } ] }, From 5b2264b3b19944d4ae1a7b03c9acf4dc654c5edb Mon Sep 17 00:00:00 2001 From: Catherine Jue Date: Fri, 24 Apr 2026 11:48:35 -0700 Subject: [PATCH 3/3] broken link --- browsers/performance.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browsers/performance.mdx b/browsers/performance.mdx index db4945b..579af08 100644 --- a/browsers/performance.mdx +++ b/browsers/performance.mdx @@ -15,7 +15,7 @@ If you're experiencing slower-than-expected browser creation (or [browser pool a 1. App code ⇔ Kernel browser region -Kernel browsers run in `us-east`. Use our [app platform](/apps/overview) to colocate your browser agent or automation. +Kernel browsers run in `us-east`. Use our [app platform](/apps/develop) to colocate your browser agent or automation. 2. Create browser rate limit