From 302048e9b3b035c107c4059b6c594ce226673196 Mon Sep 17 00:00:00 2001 From: chruffins <23645059+chruffins@users.noreply.github.com> Date: Thu, 9 Jul 2026 15:04:28 +0000 Subject: [PATCH] Document refresh_on_profile_update for browser pools --- browsers/pools/faq.mdx | 7 +++++-- browsers/pools/overview.mdx | 16 ++++++++++++++++ 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/browsers/pools/faq.mdx b/browsers/pools/faq.mdx index 7a22d87..119a59b 100644 --- a/browsers/pools/faq.mdx +++ b/browsers/pools/faq.mdx @@ -32,9 +32,12 @@ You have three ways to get it onto the new configuration: release it with `reuse ### If I update a profile's contents, will my pool's idle browsers pick up the change? -No. Idle browsers in a pool are pre-loaded with the profile's contents at the time they were filled. Updating the profile (for example, re-saving auth state to the same `profile_id`) does not propagate to already-warmed browsers — only newly-filled browsers will use the updated profile. +Not by default. Idle browsers in a pool are pre-loaded with the profile's contents at the time they were filled. Updating the profile (for example, re-saving auth state to the same `profile_id`) does not propagate to already-warmed browsers — only newly-filled browsers will use the updated profile. -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`. +To force the pool to pick up new profile contents, you have two options: + +- **Automatic**: Enable `refresh_on_profile_update` on the pool (see [Refresh on profile update](/browsers/pools/overview#refresh-on-profile-update)). When the profile is saved, the pool automatically flushes idle browsers so they are replaced with fresh ones using the updated profile. +- **Manual**: 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? diff --git a/browsers/pools/overview.mdx b/browsers/pools/overview.mdx index b494069..3a131c7 100644 --- a/browsers/pools/overview.mdx +++ b/browsers/pools/overview.mdx @@ -125,6 +125,8 @@ Pools can be pre-configured with options like start url, custom extensions, supp 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). +When a pool has a profile attached, you can optionally enable `refresh_on_profile_update` to automatically flush idle browsers whenever the profile's contents are updated — so the pool always picks up the latest profile data. See [Refresh on profile update](#refresh-on-profile-update) below. + ## 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). @@ -236,6 +238,20 @@ The `size` parameter is always required when updating a pool, even if you only w By default (`discard_all_idle: false`), updating a pool leaves existing idle browsers untouched — they keep their original configuration, and only browsers created after the update use the new configuration. Set `discard_all_idle: true` to discard all idle browsers and rebuild them immediately with the new configuration. +## Refresh on profile update + +When a pool is configured with a [profile](/auth/profiles), the profile data is loaded into each browser when it's created. Normally, updating the profile's contents (for example, re-saving cookies or auth state to the same profile) does not propagate to already-warmed browsers — only newly-filled browsers use the updated profile. + +Set `refresh_on_profile_update: true` when creating or updating a pool to have the pool automatically flush its idle browsers whenever the profile is updated. This ensures that acquired browsers always get the latest profile data without manual intervention. + + +`refresh_on_profile_update` requires a profile to be set on the pool. Setting it on a pool without a profile returns a validation error. + + +### How it works + +When a profile is saved (for example, after a successful [Managed Auth](/auth/overview) login or a `save_changes` browser session), Kernel checks whether any browser pools use that profile with `refresh_on_profile_update` enabled. If so, all idle browsers in each matching pool are flushed — they are replaced with fresh browsers that load the updated profile. Acquired browsers are not affected; they continue running with the profile data they were created with. + Reused browsers keep the configuration they were created with. A plain `update()` rebuilds nothing that already exists — it only changes the config used for future browsers. To rebuild the idle browsers too, pass `discard_all_idle: true` (or call [`flush()`](#flush-idle-browsers)). Either way, browsers that are acquired during an update are never touched: an in-use browser keeps its original configuration, and if you then release it with `reuse: true` (the default) it re-enters the pool still carrying that stale configuration and keeps getting handed out that way.