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).