From 4dff833cd3c1ba5452a1c018d08540dcb11fd176 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 1/4] 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 f12daff55862308997611a4716a2cf351651d223 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 2/4] 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 032fb4024c464d40491abd70770b5741e7c66081 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 3/4] 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 47bb68572180be2233b9b38c32c19680e314a63c 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 4/4] 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.