From 6df24c231b4835daa279ee37e13fbca842b24a75 Mon Sep 17 00:00:00 2001 From: tnsardesai <18272584+tnsardesai@users.noreply.github.com> Date: Fri, 18 Sep 2026 08:13:48 +0000 Subject: [PATCH 01/11] Document browser location controls --- browsers/location.mdx | 131 +++++++++++++++++++++++++++++++++++++ introduction/configure.mdx | 1 + 2 files changed, 132 insertions(+) create mode 100644 browsers/location.mdx diff --git a/browsers/location.mdx b/browsers/location.mdx new file mode 100644 index 00000000..3e588f70 --- /dev/null +++ b/browsers/location.mdx @@ -0,0 +1,131 @@ +--- +title: "Browser Location" +description: "Align a browser session's timezone and locale with its proxy geography or set explicit overrides" +--- + +KERNEL selects one timezone and formatting locale for each browser session. By default, it resolves each field from the browser's effective proxy geography and falls back to the browser's region while resolution is pending or unavailable. + +The setting applies across browser contexts, pages, frames, workers, `Intl`, `navigator.language`, `navigator.languages`, and future `Accept-Language` headers. Updating it doesn't restart Chromium or reload pages. + + +Location controls timezone and language behavior. It doesn't set geolocation coordinates, grant geolocation permission, change the system clock, translate browser UI, or guarantee a bot-detection outcome. + + +## Set location when creating a browser + +Set either field independently. Omit a field to let KERNEL select it automatically. + + +```typescript TypeScript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); +const browser = await kernel.browsers.create({ + proxy: { name: 'berlin-checkout' }, + location: { + timezone: 'Europe/Berlin', + locale: 'de-DE', + }, +}); + +console.log(browser.location); +``` + +```python Python +from kernel import Kernel + +kernel = Kernel() +browser = kernel.browsers.create( + proxy={"name": "berlin-checkout"}, + location={ + "timezone": "Europe/Berlin", + "locale": "de-DE", + }, +) + +print(browser.location) +``` + + +`timezone` accepts supported IANA identifiers such as `America/Los_Angeles`. `locale` accepts canonical BCP 47 tags such as `en-US` or `de-DE`. KERNEL validates the complete request before changing the session. + +## Update a running browser + +Use `browsers.update()` to set an override without restarting Chromium: + + +```typescript TypeScript +const browser = await kernel.browsers.update('01j8m3w6q2d7av9n5k4f1p8c', { + location: { + timezone: 'America/Los_Angeles', + locale: 'en-US', + }, +}); +``` + +```python Python +browser = kernel.browsers.update( + "01j8m3w6q2d7av9n5k4f1p8c", + location={ + "timezone": "America/Los_Angeles", + "locale": "en-US", + }, +) +``` + + +PATCH semantics are field-specific: + +- omit `location` or one of its fields to leave that field unchanged +- set a string to create or replace a session override +- set a field to `null` in TypeScript or `None` in Python to clear that override and resume automatic selection + + +```typescript TypeScript +const browser = await kernel.browsers.update('01j8m3w6q2d7av9n5k4f1p8c', { + location: { + timezone: null, + }, +}); +``` + +```python Python +browser = kernel.browsers.update( + "01j8m3w6q2d7av9n5k4f1p8c", + location={"timezone": None}, +) +``` + + +Clearing one field doesn't clear the other. Explicit overrides also survive proxy changes for the rest of that session. + +## Read effective location + +Browser responses include the effective values, per-field provenance, and convergence state: + +```json +{ + "location": { + "timezone": "Europe/Berlin", + "locale": "de-DE", + "timezone_source": "proxy_metadata", + "locale_source": "proxy_metadata", + "pending": false + } +} +``` + +`timezone_source` and `locale_source` can be `override`, `proxy_metadata`, `geoip`, `exit_ip`, or `metro`. KERNEL resolves the fields independently, so their sources can differ. + +When `pending` is `true`, the API has accepted the desired policy but the running browser hasn't finished converging. Browser creation and proxy updates don't wait for external geography discovery. KERNEL keeps the current values during a delayed or failed lookup and applies a valid late result in the background. + +## Runtime behavior + +- New pages, frames, workers, and network contexts start with the latest applied defaults. +- Existing pages and workers receive the update without a reload. +- Existing `Intl` formatter objects and application-level caches can retain values captured before the update. Create a new formatter when you need the latest default. +- Future requests use the updated language preference. Requests already in flight aren't rewritten. +- Customer CDP emulation remains separate from the session default and can temporarily override what a particular target reports. +- Location overrides last only for the browser session. Profiles don't save them. + +For rotating residential and mobile proxies, KERNEL resolves location when the proxy is attached or explicitly changed. It doesn't chase silent exit-IP rotation, and one discovery request doesn't represent destination-specific routes for every website. diff --git a/introduction/configure.mdx b/introduction/configure.mdx index c0b41925..3b999fc1 100644 --- a/introduction/configure.mdx +++ b/introduction/configure.mdx @@ -91,6 +91,7 @@ browser = kernel.browsers.create( Often agents don't require these, but they're there when you do: - **[Regions](/browsers/regions):** run browsers in `us-east`, `eu-west`, or `ap-southeast`, closer to your code and your users. +- **[Location](/browsers/location):** align the browser's timezone and locale with its proxy geography, or set explicit overrides without restarting Chromium. - **[Extensions](/browsers/extensions):** load unpacked Chrome extensions into a browser. - **[Chrome policies](/browsers/chrome-policies):** apply Chrome enterprise policies, such as startup pages and bookmarks. - **[Private networking](/browsers/private-networking):** reach services behind a VPN or tunnel from inside the browser session. From 233a3202c79df5f408d2e26822cffd581877e556 Mon Sep 17 00:00:00 2001 From: tnsardesai <18272584+tnsardesai@users.noreply.github.com> Date: Fri, 9 Oct 2026 10:43:50 +0000 Subject: [PATCH 02/11] Describe browser location validation and normalization --- browsers/location.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browsers/location.mdx b/browsers/location.mdx index 3e588f70..5608d0e3 100644 --- a/browsers/location.mdx +++ b/browsers/location.mdx @@ -47,7 +47,7 @@ print(browser.location) ``` -`timezone` accepts supported IANA identifiers such as `America/Los_Angeles`. `locale` accepts canonical BCP 47 tags such as `en-US` or `de-DE`. KERNEL validates the complete request before changing the session. +`timezone` accepts IANA identifiers such as `America/Los_Angeles`. `locale` accepts BCP 47 tags such as `en-US` or `de-DE` that the browser formats dates and numbers for with that exact region. KERNEL normalizes spelling and deprecated codes, so `en-us` becomes `en-US` and `iw-IL` becomes `he-IL`. KERNEL validates the complete request before changing the session and returns a `400` with code `invalid_browser_location` for an unsupported value such as `en-QQ`. ## Update a running browser From 49e6d7b88e991021205d63958b32c20dadab1668 Mon Sep 17 00:00:00 2001 From: tnsardesai <18272584+tnsardesai@users.noreply.github.com> Date: Fri, 9 Oct 2026 18:31:38 +0000 Subject: [PATCH 03/11] Document explicit browser location with region defaults Location is set explicitly per session; omitted or cleared fields use the default for the browser's region. Proxy-based selection is not documented until it ships. --- browsers/location.mdx | 34 +++++++++++++++------------------- introduction/configure.mdx | 2 +- 2 files changed, 16 insertions(+), 20 deletions(-) diff --git a/browsers/location.mdx b/browsers/location.mdx index 5608d0e3..21b73ed7 100644 --- a/browsers/location.mdx +++ b/browsers/location.mdx @@ -1,19 +1,19 @@ --- title: "Browser Location" -description: "Align a browser session's timezone and locale with its proxy geography or set explicit overrides" +description: "Set a browser session's timezone and locale, or use the defaults for its region" --- -KERNEL selects one timezone and formatting locale for each browser session. By default, it resolves each field from the browser's effective proxy geography and falls back to the browser's region while resolution is pending or unavailable. +Each browser session has one timezone and one formatting locale. By default, both come from the region the browser runs in, for example `America/New_York` and `en-US` for a browser in `us-east`. Set either field to override it for the session. The setting applies across browser contexts, pages, frames, workers, `Intl`, `navigator.language`, `navigator.languages`, and future `Accept-Language` headers. Updating it doesn't restart Chromium or reload pages. -Location controls timezone and language behavior. It doesn't set geolocation coordinates, grant geolocation permission, change the system clock, translate browser UI, or guarantee a bot-detection outcome. +Location controls timezone and language behavior. It doesn't set geolocation coordinates, grant geolocation permission, change the system clock, translate browser UI, or guarantee a bot-detection outcome. KERNEL doesn't derive location from a browser's proxy; to match a proxy's country, set the location explicitly. ## Set location when creating a browser -Set either field independently. Omit a field to let KERNEL select it automatically. +Set either field independently. An omitted field uses the default for the browser's region. ```typescript TypeScript @@ -21,7 +21,6 @@ import Kernel from '@onkernel/sdk'; const kernel = new Kernel(); const browser = await kernel.browsers.create({ - proxy: { name: 'berlin-checkout' }, location: { timezone: 'Europe/Berlin', locale: 'de-DE', @@ -36,7 +35,6 @@ from kernel import Kernel kernel = Kernel() browser = kernel.browsers.create( - proxy={"name": "berlin-checkout"}, location={ "timezone": "Europe/Berlin", "locale": "de-DE", @@ -78,7 +76,7 @@ PATCH semantics are field-specific: - omit `location` or one of its fields to leave that field unchanged - set a string to create or replace a session override -- set a field to `null` in TypeScript or `None` in Python to clear that override and resume automatic selection +- set a field to `null` in TypeScript or `None` in Python to clear that override and return to the default for the browser's region ```typescript TypeScript @@ -97,35 +95,33 @@ browser = kernel.browsers.update( ``` -Clearing one field doesn't clear the other. Explicit overrides also survive proxy changes for the rest of that session. +Clearing one field doesn't clear the other. Overrides stay in place when you change the browser's proxy. ## Read effective location -Browser responses include the effective values, per-field provenance, and convergence state: +Browser responses include the effective values, where each came from, and convergence state: ```json { "location": { - "timezone": "Europe/Berlin", - "locale": "de-DE", - "timezone_source": "proxy_metadata", - "locale_source": "proxy_metadata", + "timezone": "America/Los_Angeles", + "locale": "en-US", + "timezone_source": "override", + "locale_source": "metro", "pending": false } } ``` -`timezone_source` and `locale_source` can be `override`, `proxy_metadata`, `geoip`, `exit_ip`, or `metro`. KERNEL resolves the fields independently, so their sources can differ. +`timezone_source` and `locale_source` are `override` for a value set on the session and `metro` for the default of the browser's region. The fields are independent, so their sources can differ. -When `pending` is `true`, the API has accepted the desired policy but the running browser hasn't finished converging. Browser creation and proxy updates don't wait for external geography discovery. KERNEL keeps the current values during a delayed or failed lookup and applies a valid late result in the background. +When `pending` is `true`, the API has accepted the change but the running browser hasn't finished applying it. Browser creation doesn't wait for it. ## Runtime behavior -- New pages, frames, workers, and network contexts start with the latest applied defaults. +- New pages, frames, workers, and network contexts start with the latest applied values. - Existing pages and workers receive the update without a reload. - Existing `Intl` formatter objects and application-level caches can retain values captured before the update. Create a new formatter when you need the latest default. - Future requests use the updated language preference. Requests already in flight aren't rewritten. - Customer CDP emulation remains separate from the session default and can temporarily override what a particular target reports. -- Location overrides last only for the browser session. Profiles don't save them. - -For rotating residential and mobile proxies, KERNEL resolves location when the proxy is attached or explicitly changed. It doesn't chase silent exit-IP rotation, and one discovery request doesn't represent destination-specific routes for every website. +- Location overrides last only for the browser session. Profiles don't save them, and a browser returned to a pool loses them before its next lease. diff --git a/introduction/configure.mdx b/introduction/configure.mdx index 3b999fc1..bf791a33 100644 --- a/introduction/configure.mdx +++ b/introduction/configure.mdx @@ -91,7 +91,7 @@ browser = kernel.browsers.create( Often agents don't require these, but they're there when you do: - **[Regions](/browsers/regions):** run browsers in `us-east`, `eu-west`, or `ap-southeast`, closer to your code and your users. -- **[Location](/browsers/location):** align the browser's timezone and locale with its proxy geography, or set explicit overrides without restarting Chromium. +- **[Location](/browsers/location):** set the browser's timezone and locale for the session without restarting Chromium; otherwise they follow the browser's region. - **[Extensions](/browsers/extensions):** load unpacked Chrome extensions into a browser. - **[Chrome policies](/browsers/chrome-policies):** apply Chrome enterprise policies, such as startup pages and bookmarks. - **[Private networking](/browsers/private-networking):** reach services behind a VPN or tunnel from inside the browser session. From 1b3d90acae389664d283c4594a0e88e2a3fd8da2 Mon Sep 17 00:00:00 2001 From: tnsardesai <18272584+tnsardesai@users.noreply.github.com> Date: Fri, 9 Oct 2026 23:05:59 +0000 Subject: [PATCH 04/11] Link browser location defaults to regions --- browsers/location.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browsers/location.mdx b/browsers/location.mdx index 21b73ed7..4c7c9425 100644 --- a/browsers/location.mdx +++ b/browsers/location.mdx @@ -3,7 +3,7 @@ title: "Browser Location" description: "Set a browser session's timezone and locale, or use the defaults for its region" --- -Each browser session has one timezone and one formatting locale. By default, both come from the region the browser runs in, for example `America/New_York` and `en-US` for a browser in `us-east`. Set either field to override it for the session. +Each browser session has one timezone and one formatting locale. By default, both come from the [region](/browsers/regions) the browser runs in, for example `America/New_York` and `en-US` for a browser in `us-east`. Set either field to override it for the session. The setting applies across browser contexts, pages, frames, workers, `Intl`, `navigator.language`, `navigator.languages`, and future `Accept-Language` headers. Updating it doesn't restart Chromium or reload pages. From bc35fe2405b7f75584852087a402861330b2305a Mon Sep 17 00:00:00 2001 From: tnsardesai <18272584+tnsardesai@users.noreply.github.com> Date: Tue, 13 Oct 2026 19:17:13 +0000 Subject: [PATCH 05/11] Document synchronous browser location updates --- browsers/location.mdx | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/browsers/location.mdx b/browsers/location.mdx index 4c7c9425..7702fe15 100644 --- a/browsers/location.mdx +++ b/browsers/location.mdx @@ -47,9 +47,11 @@ print(browser.location) `timezone` accepts IANA identifiers such as `America/Los_Angeles`. `locale` accepts BCP 47 tags such as `en-US` or `de-DE` that the browser formats dates and numbers for with that exact region. KERNEL normalizes spelling and deprecated codes, so `en-us` becomes `en-US` and `iw-IL` becomes `he-IL`. KERNEL validates the complete request before changing the session and returns a `400` with code `invalid_browser_location` for an unsupported value such as `en-QQ`. +The create call returns after the browser applies the location, so the first page you open already uses it. If the browser can't apply it, KERNEL discards the browser and returns a `500`. Retry the request to get a new browser. + ## Update a running browser -Use `browsers.update()` to set an override without restarting Chromium: +Use `browsers.update()` to set an override without restarting Chromium. The update returns after the running browser applies the new location: ```typescript TypeScript @@ -97,9 +99,15 @@ browser = kernel.browsers.update( Clearing one field doesn't clear the other. Overrides stay in place when you change the browser's proxy. +When an update doesn't take effect, the error tells you what to do next: + +- `409` with code `conflict`: another update changed the browser's location at the same time. Retry the request. +- `400` with code `browser_location_unsupported`: the browser runs an image that can't change location. Create a new browser. +- `500`: the browser didn't confirm the new location. Retry the request. + ## Read effective location -Browser responses include the effective values, where each came from, and convergence state: +Browser responses include the effective values and where each came from: ```json { @@ -107,16 +115,13 @@ Browser responses include the effective values, where each came from, and conver "timezone": "America/Los_Angeles", "locale": "en-US", "timezone_source": "override", - "locale_source": "metro", - "pending": false + "locale_source": "metro" } } ``` `timezone_source` and `locale_source` are `override` for a value set on the session and `metro` for the default of the browser's region. The fields are independent, so their sources can differ. -When `pending` is `true`, the API has accepted the change but the running browser hasn't finished applying it. Browser creation doesn't wait for it. - ## Runtime behavior - New pages, frames, workers, and network contexts start with the latest applied values. From 2b6b4bd3d9ef93b4be8943c82dfeee06e0e2f5f0 Mon Sep 17 00:00:00 2001 From: tnsardesai <18272584+tnsardesai@users.noreply.github.com> Date: Tue, 13 Oct 2026 20:15:31 +0000 Subject: [PATCH 06/11] Document that reused pool browsers keep their location --- browsers/location.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/browsers/location.mdx b/browsers/location.mdx index 7702fe15..a44957b3 100644 --- a/browsers/location.mdx +++ b/browsers/location.mdx @@ -129,4 +129,5 @@ Browser responses include the effective values and where each came from: - Existing `Intl` formatter objects and application-level caches can retain values captured before the update. Create a new formatter when you need the latest default. - Future requests use the updated language preference. Requests already in flight aren't rewritten. - Customer CDP emulation remains separate from the session default and can temporarily override what a particular target reports. -- Location overrides last only for the browser session. Profiles don't save them, and a browser returned to a pool loses them before its next lease. +- Location overrides last only for the browser session, and profiles don't save them. +- A pooled browser released with `reuse: true` keeps its location for the next acquirer, as it keeps cookies and open tabs. Release with `reuse: false` to get a fresh browser. From 9c998788282abf2e65e95e40ea0799e8d733e339 Mon Sep 17 00:00:00 2001 From: tnsardesai <18272584+tnsardesai@users.noreply.github.com> Date: Tue, 13 Oct 2026 20:57:33 +0000 Subject: [PATCH 07/11] Document the unsupported-image create response --- browsers/location.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browsers/location.mdx b/browsers/location.mdx index a44957b3..fd5edbc5 100644 --- a/browsers/location.mdx +++ b/browsers/location.mdx @@ -47,7 +47,7 @@ print(browser.location) `timezone` accepts IANA identifiers such as `America/Los_Angeles`. `locale` accepts BCP 47 tags such as `en-US` or `de-DE` that the browser formats dates and numbers for with that exact region. KERNEL normalizes spelling and deprecated codes, so `en-us` becomes `en-US` and `iw-IL` becomes `he-IL`. KERNEL validates the complete request before changing the session and returns a `400` with code `invalid_browser_location` for an unsupported value such as `en-QQ`. -The create call returns after the browser applies the location, so the first page you open already uses it. If the browser can't apply it, KERNEL discards the browser and returns a `500`. Retry the request to get a new browser. +The create call returns after the browser applies the location, so the first page you open already uses it. If the browser can't apply it, KERNEL discards the browser and returns a `500`. Retry the request to get a new browser. If the assigned browser's image can't change location, KERNEL discards it and returns a `400` with code `browser_location_unsupported` instead. Try again later, or create the browser without `location`. ## Update a running browser From 3f7b8b7d3e5f54ed92566ed3df849d890fad6466 Mon Sep 17 00:00:00 2001 From: tnsardesai <18272584+tnsardesai@users.noreply.github.com> Date: Wed, 14 Oct 2026 03:48:48 +0000 Subject: [PATCH 08/11] Explain what a failed location update leaves applied --- browsers/location.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/browsers/location.mdx b/browsers/location.mdx index fd5edbc5..c5ab618b 100644 --- a/browsers/location.mdx +++ b/browsers/location.mdx @@ -99,11 +99,11 @@ browser = kernel.browsers.update( Clearing one field doesn't clear the other. Overrides stay in place when you change the browser's proxy. -When an update doesn't take effect, the error tells you what to do next: +KERNEL checks that the browser can change location before it applies anything else in the request, and applies the location last. When an update doesn't take effect, the error tells you what to do next: - `409` with code `conflict`: another update changed the browser's location at the same time. Retry the request. -- `400` with code `browser_location_unsupported`: the browser runs an image that can't change location. Create a new browser. -- `500`: the browser didn't confirm the new location. Retry the request. +- `400` with code `browser_location_unsupported`: the browser runs an image that can't change location. Nothing in the request is applied. Create a new browser. +- `500`: the browser didn't confirm the new location. The request's other changes and the new override are already saved, so retry the same request to apply the location. ## Read effective location From e431b9b4c8f0a7b7557c94ed657129b2135f83d0 Mon Sep 17 00:00:00 2001 From: tnsardesai <18272584+tnsardesai@users.noreply.github.com> Date: Wed, 14 Oct 2026 21:34:39 +0000 Subject: [PATCH 09/11] Shorten the location entry on the configure page --- introduction/configure.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/introduction/configure.mdx b/introduction/configure.mdx index bf791a33..061814f0 100644 --- a/introduction/configure.mdx +++ b/introduction/configure.mdx @@ -91,7 +91,7 @@ browser = kernel.browsers.create( Often agents don't require these, but they're there when you do: - **[Regions](/browsers/regions):** run browsers in `us-east`, `eu-west`, or `ap-southeast`, closer to your code and your users. -- **[Location](/browsers/location):** set the browser's timezone and locale for the session without restarting Chromium; otherwise they follow the browser's region. +- **[Location](/browsers/location):** set the browser's timezone and locale. - **[Extensions](/browsers/extensions):** load unpacked Chrome extensions into a browser. - **[Chrome policies](/browsers/chrome-policies):** apply Chrome enterprise policies, such as startup pages and bookmarks. - **[Private networking](/browsers/private-networking):** reach services behind a VPN or tunnel from inside the browser session. From ad504ba3c3803d432310897d73802e77894ef387 Mon Sep 17 00:00:00 2001 From: tnsardesai <18272584+tnsardesai@users.noreply.github.com> Date: Wed, 14 Oct 2026 21:39:24 +0000 Subject: [PATCH 10/11] Describe browser location as it behaves once fully rolled out --- browsers/location.mdx | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/browsers/location.mdx b/browsers/location.mdx index c5ab618b..4d7dfed8 100644 --- a/browsers/location.mdx +++ b/browsers/location.mdx @@ -45,13 +45,11 @@ print(browser.location) ``` -`timezone` accepts IANA identifiers such as `America/Los_Angeles`. `locale` accepts BCP 47 tags such as `en-US` or `de-DE` that the browser formats dates and numbers for with that exact region. KERNEL normalizes spelling and deprecated codes, so `en-us` becomes `en-US` and `iw-IL` becomes `he-IL`. KERNEL validates the complete request before changing the session and returns a `400` with code `invalid_browser_location` for an unsupported value such as `en-QQ`. - -The create call returns after the browser applies the location, so the first page you open already uses it. If the browser can't apply it, KERNEL discards the browser and returns a `500`. Retry the request to get a new browser. If the assigned browser's image can't change location, KERNEL discards it and returns a `400` with code `browser_location_unsupported` instead. Try again later, or create the browser without `location`. +`timezone` accepts IANA identifiers such as `America/Los_Angeles`. `locale` accepts BCP 47 tags such as `en-US` or `de-DE` that the browser formats dates and numbers for with that exact region. KERNEL normalizes spelling and deprecated codes, so `en-us` becomes `en-US` and `iw-IL` becomes `he-IL`. An unsupported value such as `en-QQ` returns a `400` with code `invalid_browser_location`. ## Update a running browser -Use `browsers.update()` to set an override without restarting Chromium. The update returns after the running browser applies the new location: +Use `browsers.update()` to set an override on a running browser: ```typescript TypeScript @@ -99,12 +97,6 @@ browser = kernel.browsers.update( Clearing one field doesn't clear the other. Overrides stay in place when you change the browser's proxy. -KERNEL checks that the browser can change location before it applies anything else in the request, and applies the location last. When an update doesn't take effect, the error tells you what to do next: - -- `409` with code `conflict`: another update changed the browser's location at the same time. Retry the request. -- `400` with code `browser_location_unsupported`: the browser runs an image that can't change location. Nothing in the request is applied. Create a new browser. -- `500`: the browser didn't confirm the new location. The request's other changes and the new override are already saved, so retry the same request to apply the location. - ## Read effective location Browser responses include the effective values and where each came from: @@ -124,7 +116,7 @@ Browser responses include the effective values and where each came from: ## Runtime behavior -- New pages, frames, workers, and network contexts start with the latest applied values. +- New pages, frames, workers, and network contexts start with the current location. - Existing pages and workers receive the update without a reload. - Existing `Intl` formatter objects and application-level caches can retain values captured before the update. Create a new formatter when you need the latest default. - Future requests use the updated language preference. Requests already in flight aren't rewritten. From 4d9d122bf3b55dcec9e09ebdff66562d50c62257 Mon Sep 17 00:00:00 2001 From: tnsardesai <18272584+tnsardesai@users.noreply.github.com> Date: Mon, 19 Oct 2026 23:39:49 +0000 Subject: [PATCH 11/11] Simplify the browser location page Drop the proxy note and the response source values, show updates against the created browser's session ID with the update rules as code comments, and describe how changes take effect in plainer language. --- browsers/location.mdx | 62 +++++++++++++++++-------------------------- 1 file changed, 24 insertions(+), 38 deletions(-) diff --git a/browsers/location.mdx b/browsers/location.mdx index 4d7dfed8..60ac612f 100644 --- a/browsers/location.mdx +++ b/browsers/location.mdx @@ -8,7 +8,7 @@ Each browser session has one timezone and one formatting locale. By default, bot The setting applies across browser contexts, pages, frames, workers, `Intl`, `navigator.language`, `navigator.languages`, and future `Accept-Language` headers. Updating it doesn't restart Chromium or reload pages. -Location controls timezone and language behavior. It doesn't set geolocation coordinates, grant geolocation permission, change the system clock, translate browser UI, or guarantee a bot-detection outcome. KERNEL doesn't derive location from a browser's proxy; to match a proxy's country, set the location explicitly. +Location controls timezone and language behavior. It doesn't set geolocation coordinates, grant geolocation permission, change the system clock, translate browser UI, or guarantee a bot-detection outcome. ## Set location when creating a browser @@ -49,57 +49,45 @@ print(browser.location) ## Update a running browser -Use `browsers.update()` to set an override on a running browser: +Use `browsers.update()` to change the location of a running browser: ```typescript TypeScript -const browser = await kernel.browsers.update('01j8m3w6q2d7av9n5k4f1p8c', { +// Set a field to override it. Fields you leave out keep their current value. +await kernel.browsers.update(browser.session_id, { location: { timezone: 'America/Los_Angeles', locale: 'en-US', }, }); + +// Set a field to null to go back to the default for the browser's region. +await kernel.browsers.update(browser.session_id, { + location: { timezone: null }, +}); ``` ```python Python -browser = kernel.browsers.update( - "01j8m3w6q2d7av9n5k4f1p8c", +# Set a field to override it. Fields you leave out keep their current value. +kernel.browsers.update( + browser.session_id, location={ "timezone": "America/Los_Angeles", "locale": "en-US", }, ) -``` - - -PATCH semantics are field-specific: - -- omit `location` or one of its fields to leave that field unchanged -- set a string to create or replace a session override -- set a field to `null` in TypeScript or `None` in Python to clear that override and return to the default for the browser's region - - -```typescript TypeScript -const browser = await kernel.browsers.update('01j8m3w6q2d7av9n5k4f1p8c', { - location: { - timezone: null, - }, -}); -``` -```python Python -browser = kernel.browsers.update( - "01j8m3w6q2d7av9n5k4f1p8c", +# Set a field to None to go back to the default for the browser's region. +kernel.browsers.update( + browser.session_id, location={"timezone": None}, ) ``` -Clearing one field doesn't clear the other. Overrides stay in place when you change the browser's proxy. - ## Read effective location -Browser responses include the effective values and where each came from: +Browser responses include the timezone and locale the browser is using, and whether each one is your override or the region's default: ```json { @@ -112,14 +100,12 @@ Browser responses include the effective values and where each came from: } ``` -`timezone_source` and `locale_source` are `override` for a value set on the session and `metro` for the default of the browser's region. The fields are independent, so their sources can differ. - -## Runtime behavior +## How changes take effect -- New pages, frames, workers, and network contexts start with the current location. -- Existing pages and workers receive the update without a reload. -- Existing `Intl` formatter objects and application-level caches can retain values captured before the update. Create a new formatter when you need the latest default. -- Future requests use the updated language preference. Requests already in flight aren't rewritten. -- Customer CDP emulation remains separate from the session default and can temporarily override what a particular target reports. -- Location overrides last only for the browser session, and profiles don't save them. -- A pooled browser released with `reuse: true` keeps its location for the next acquirer, as it keeps cookies and open tabs. Release with `reuse: false` to get a fresh browser. +- Open tabs pick up a change right away, without reloading. +- New tabs and frames start with the current timezone and locale. +- Date and number formatters a page already created keep their original settings. Create a new one, such as `new Intl.DateTimeFormat()`, to use the new values. +- Requests already in progress keep their original language. Later requests use the new one. +- A timezone or locale you set yourself through Playwright or Puppeteer, such as Playwright's `timezoneId`, takes precedence on the pages it applies to. +- The location lasts for the browser session. Profiles don't save it. +- A pooled browser you release with `reuse: true` keeps its location for the next acquirer, just as it keeps cookies and open tabs. Release it with `reuse: false` to get a fresh browser instead.