From 3da99431d6f6a652088524eab8f1768e31ab749a Mon Sep 17 00:00:00 2001 From: Ilyaas Kapadia <86218345+IlyaasK@users.noreply.github.com> Date: Fri, 26 Jun 2026 14:13:02 -0400 Subject: [PATCH] docs: clarify pooled browsers don't persist profile changes (save_changes) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit save_changes:true on a browser pool used to return 400 and is now a silent no-op (kernel/kernel#2484). Document that pooled browsers load a profile read-only and never persist changes back to it — save_changes applies only to single browser sessions — so users don't expect pooled browsers to save state. - browsers/pools/faq.mdx: new "Can pooled browsers save changes back to a profile?" Q&A - auth/profiles.mdx: Notes bullet scoping save_changes to single sessions - browsers/pools/overview.mdx: read-only profile caveat under pool config options Per review note on kernel/kernel#2484. Co-Authored-By: Claude Opus 4.8 (1M context) --- auth/profiles.mdx | 1 + browsers/pools/faq.mdx | 4 ++++ browsers/pools/overview.mdx | 2 ++ 3 files changed, 7 insertions(+) diff --git a/auth/profiles.mdx b/auth/profiles.mdx index 5833b55..4f47c72 100644 --- a/auth/profiles.mdx +++ b/auth/profiles.mdx @@ -484,4 +484,5 @@ _ = browser - Profiles store cookies and local storage. Start the session with `save_changes: true` to write changes back when the browser is closed. - To keep a profile immutable for a run, omit `save_changes` (default) when creating the browser. - Multiple browsers in parallel can use the same profile, but only one browser should write (`save_changes: true`) to it at a time. Parallel browsers with `save_changes: true` may cause profile corruption and unpredictable behavior. +- `save_changes` applies only to single browser sessions (`kernel.browsers.create()`). [Browser pools](/browsers/pools/overview) load a profile read-only and never persist changes back to it; `save_changes` sent on a pool's profile is silently ignored. - Profile data is encrypted end to end using a per-organization key. diff --git a/browsers/pools/faq.mdx b/browsers/pools/faq.mdx index 327abb5..9098d83 100644 --- a/browsers/pools/faq.mdx +++ b/browsers/pools/faq.mdx @@ -30,6 +30,10 @@ No. Idle browsers in a pool are pre-loaded with the profile's contents at the ti To force the pool to pick up new profile contents, either call `kernel.browserPools.flush()` to destroy idle browsers (the pool refills automatically), or call `kernel.browserPools.update()` with `discard_all_idle: true`. +### Can pooled browsers save changes back to a profile? + +No. A profile attached to a pool is loaded read-only — pooled browsers never persist changes back to the profile, so `save_changes` does not apply to pools. Sending `save_changes` on a pool's profile is silently ignored (it is not rejected), so reusing a single-session profile object won't error. To capture profile state, use a single browser session instead: `kernel.browsers.create({ profile: { name, save_changes: true } })`. + ### Should I set `reuse: true` or `reuse: false` when releasing? Use `reuse: true` (default) for efficiency. Only use `reuse: false` when you suspect browser state corruption or need a guaranteed clean browser session. diff --git a/browsers/pools/overview.mdx b/browsers/pools/overview.mdx index d3ffd1c..80bfb45 100644 --- a/browsers/pools/overview.mdx +++ b/browsers/pools/overview.mdx @@ -123,6 +123,8 @@ func main() { Pools can be pre-configured with options like start url, custom extensions, supported viewports, residential proxies, profiles, and more. See the [API reference](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool) for more details. +A profile attached to a pool is loaded read-only: pooled browsers never persist changes back to the profile, so `save_changes` does not apply to pools (it is silently ignored if sent). To capture profile state, use a single browser session with `save_changes` instead — see [Profiles](/auth/profiles). + ## Acquire a browser Acquire a browser from the 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; it defaults to the calculated time it would take to fill the pool at the pool's configured [fill rate](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-fill-rate-per-minute).