From 33bd788fdefa9fa1dacae1440a610ebd57d993d9 Mon Sep 17 00:00:00 2001 From: chruffins <23645059+chruffins@users.noreply.github.com> Date: Fri, 10 Jul 2026 19:15:00 +0000 Subject: [PATCH] update docs: refresh_on_profile_update now defaults to true when profile attached The API now auto-defaults refresh_on_profile_update to true when a pool is created with a profile or when the pool's profile reference changes. When a profile is removed, it's forced to false. See kernel/kernel PR #2708 for the implementation. --- browsers/pools/faq.mdx | 7 +++---- browsers/pools/overview.mdx | 8 +++++--- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/browsers/pools/faq.mdx b/browsers/pools/faq.mdx index 119a59b..e78e791 100644 --- a/browsers/pools/faq.mdx +++ b/browsers/pools/faq.mdx @@ -32,12 +32,11 @@ 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? -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. +By default, yes — `refresh_on_profile_update` is automatically set to `true` when a pool is created with a profile or when the pool's profile is changed. Idle browsers are flushed whenever the profile is saved, so they get replaced with fresh ones using the updated profile. -To force the pool to pick up new profile contents, you have two options: +If you've explicitly disabled `refresh_on_profile_update`, you can still force the pool to pick up new profile contents: -- **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`. +- **Manual**: Call `kernel.browserPools.flush()` to destroy idle browsers (the pool refills automatically), or call `kernel.browserPools.update()` with `discard_all_idle: true`. See [Refresh on profile update](/browsers/pools/overview#refresh-on-profile-update). ### Can pooled browsers save changes back to a profile? diff --git a/browsers/pools/overview.mdx b/browsers/pools/overview.mdx index a589491..0fc3d6a 100644 --- a/browsers/pools/overview.mdx +++ b/browsers/pools/overview.mdx @@ -127,7 +127,7 @@ 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. +When a pool has a profile attached, `refresh_on_profile_update` is automatically enabled — the pool flushes idle browsers whenever the profile's contents are updated, so it always picks up the latest profile data. See [Refresh on profile update](#refresh-on-profile-update) below. ## Acquire a browser @@ -244,10 +244,12 @@ By default (`discard_all_idle: false`), updating a pool leaves existing idle bro 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` is automatically set to `true` when a pool is created with a profile, or when an existing pool's profile is changed. This ensures that acquired browsers always get the latest profile data without manual intervention. You can explicitly set it to `false` to opt out. + +When a pool's profile is removed (by passing `{ "id": "" }`), `refresh_on_profile_update` is forced to `false`. -`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. +`refresh_on_profile_update` requires a profile to be set on the pool. Setting it explicitly to `true` on a pool without a profile returns a validation error. When created without a profile, it defaults to `false`. ### How it works