From efd248d561d83c56e70faafe01ebc7736dca7146 Mon Sep 17 00:00:00 2001 From: yummybomb <19238148+yummybomb@users.noreply.github.com> Date: Wed, 13 May 2026 18:42:42 +0000 Subject: [PATCH 1/6] docs: add start_url to browsers.create and browser pools --- browsers/create-a-browser.mdx | 26 ++++++++++++++++++++++++++ browsers/pools/overview.mdx | 16 ++++++++++++++++ browsers/pools/policy-json.mdx | 4 ++++ reference/cli/browsers.mdx | 4 ++++ 4 files changed, 50 insertions(+) diff --git a/browsers/create-a-browser.mdx b/browsers/create-a-browser.mdx index 17071db..b975bd5 100644 --- a/browsers/create-a-browser.mdx +++ b/browsers/create-a-browser.mdx @@ -35,6 +35,32 @@ print(kernel_browser.session_id) ``` +### Start on a specific URL + +Pass `start_url` to have Kernel navigate the browser to a URL when it starts. Navigation is best-effort: failures do not fail browser creation, and the response records the requested `start_url` for debugging. + + +```typescript Typescript/Javascript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); + +const kernelBrowser = await kernel.browsers.create({ + start_url: 'https://example.com', +}); +``` + +```python Python +from kernel import Kernel + +kernel = Kernel() + +kernel_browser = kernel.browsers.create( + start_url="https://example.com", +) +``` + + ## 2. Connect to the browser diff --git a/browsers/pools/overview.mdx b/browsers/pools/overview.mdx index 557b1f2..470d39a 100644 --- a/browsers/pools/overview.mdx +++ b/browsers/pools/overview.mdx @@ -52,6 +52,7 @@ const pool = await kernel.browserPools.create({ stealth: true, headless: false, timeout_seconds: 600, + start_url: "https://example.com", viewport: { width: 1280, height: 800 @@ -72,6 +73,7 @@ pool = kernel.browser_pools.create( stealth=True, headless=False, timeout_seconds=600, + start_url="https://example.com", viewport={ "width": 1280, "height": 800 @@ -82,6 +84,16 @@ print(pool.id) ``` +### Start URL + +Pass `start_url` to have Kernel navigate newly created browsers in the pool before they become available for acquisition. Navigation is best-effort: failures do not fail pool fill, and the response records the requested `start_url` for debugging. + + +When using `start_url` with [`chrome_policy`](/browsers/pools/policy-json), `start_url` takes precedence over startup URLs configured via Chrome policies, such as `RestoreOnStartupURLs`. + +When releasing a browser with `reuse: true`, the reused browser may no longer be on the `start_url`. `start_url` applies when new browsers are created in the pool. + + ### Pool configuration options Pools can be pre-configured with options like 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. @@ -147,6 +159,7 @@ Update the pool configuration. By default, all idle browsers are discarded and r const updatedPool = await kernel.browserPools.update("my-pool", { size: 20, stealth: true, + start_url: "https://example.com", }); ``` @@ -155,6 +168,7 @@ updated_pool = kernel.browser_pools.update( "my-pool", size=20, stealth=True, + start_url="https://example.com", ) ``` @@ -163,6 +177,8 @@ updated_pool = kernel.browser_pools.update( The `size` parameter is always required when updating a pool, even if you only want to change other settings. +Set `start_url` to a new URL to change where newly created browsers in the pool start. Set `start_url` to an empty string to clear it. + By default, updating a pool discards all idle browsers and rebuilds them with the new configuration. Set `discard_all_idle: false` to keep existing idle browsers and only apply the new configuration to newly created browsers. ## Flush idle browsers diff --git a/browsers/pools/policy-json.mdx b/browsers/pools/policy-json.mdx index 1bd9c0d..f83c772 100644 --- a/browsers/pools/policy-json.mdx +++ b/browsers/pools/policy-json.mdx @@ -127,6 +127,10 @@ The example above demonstrates setting a default homepage and managed bookmarks. | `BookmarkBarEnabled` | `boolean` | Shows the bookmark bar | | `ManagedBookmarks` | `array` | Pre-configured bookmarks. Supports folders via nested `children` arrays | +## Interaction with `start_url` + +If you set [`start_url`](/browsers/pools/overview#start-url) on a pool, Kernel attempts that navigation after browser startup, so it takes precedence over startup URLs configured via Chrome policies, such as `RestoreOnStartup` / `RestoreOnStartupURLs`. + ## Available policies Any policy listed in the [Chrome Enterprise policy documentation](https://chromeenterprise.google/policies/) can be used in the `chrome_policy` object. Refer to the official docs for the full list of supported policy names, types, and values. diff --git a/reference/cli/browsers.mdx b/reference/cli/browsers.mdx index 66b8a4a..0b7586e 100644 --- a/reference/cli/browsers.mdx +++ b/reference/cli/browsers.mdx @@ -21,6 +21,7 @@ Create a new browser session. | `--stealth` | Enable stealth mode to reduce automation fingerprints. | | `--headless` | Launch without GUI/VNC access. | | `--kiosk` | Launch in Chrome kiosk mode. | +| `--start-url ` | Initial page to open on launch. | | `--output json`, `-o json` | Output raw JSON object. | ### `kernel browsers delete ` @@ -432,6 +433,7 @@ Create a new browser pool. | `--size ` | Number of browsers in the pool (required). | | `--fill-rate ` | Percentage of the pool to fill per minute. | | `--timeout ` | Idle timeout for browsers acquired from the pool. | +| `--start-url ` | Initial page to open for new browsers. | | `--output json`, `-o json` | Output raw JSON object. | ### `kernel browser-pools get ` @@ -447,6 +449,8 @@ Update pool configuration. | Flag | Description | |------|-------------| | `--size ` | Updated pool size. | +| `--start-url ` | Initial page to open for new browsers. | +| `--clear-start-url` | Clear the pool start URL. | | `--discard-all-idle` | Discard all idle browsers and refill. | | `--output json`, `-o json` | Output raw JSON object. | From 67f6ac24584befb3ddfff548629d4cd4303b996d Mon Sep 17 00:00:00 2001 From: Nicholas Chen Date: Wed, 13 May 2026 17:26:02 -0400 Subject: [PATCH 2/6] Update 'start_url' explanation in create-a-browser.mdx Clarified the explanation of 'start_url' behavior during browser creation. --- browsers/create-a-browser.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browsers/create-a-browser.mdx b/browsers/create-a-browser.mdx index b975bd5..b622021 100644 --- a/browsers/create-a-browser.mdx +++ b/browsers/create-a-browser.mdx @@ -37,7 +37,7 @@ print(kernel_browser.session_id) ### Start on a specific URL -Pass `start_url` to have Kernel navigate the browser to a URL when it starts. Navigation is best-effort: failures do not fail browser creation, and the response records the requested `start_url` for debugging. +Pass `start_url` to have Kernel navigate the browser to a URL when it starts. Navigation is best-effort which means failures do not fail browser creation. ```typescript Typescript/Javascript From 49e47691c9e3d90dfc78aa92307eaaf1ab40457c Mon Sep 17 00:00:00 2001 From: yummybomb <19238148+yummybomb@users.noreply.github.com> Date: Wed, 13 May 2026 19:35:37 +0000 Subject: [PATCH 3/6] docs: limit start_url docs to CLI reference --- browsers/create-a-browser.mdx | 26 -------------------------- browsers/pools/overview.mdx | 16 ---------------- browsers/pools/policy-json.mdx | 4 ---- 3 files changed, 46 deletions(-) diff --git a/browsers/create-a-browser.mdx b/browsers/create-a-browser.mdx index b622021..17071db 100644 --- a/browsers/create-a-browser.mdx +++ b/browsers/create-a-browser.mdx @@ -35,32 +35,6 @@ print(kernel_browser.session_id) ``` -### Start on a specific URL - -Pass `start_url` to have Kernel navigate the browser to a URL when it starts. Navigation is best-effort which means failures do not fail browser creation. - - -```typescript Typescript/Javascript -import Kernel from '@onkernel/sdk'; - -const kernel = new Kernel(); - -const kernelBrowser = await kernel.browsers.create({ - start_url: 'https://example.com', -}); -``` - -```python Python -from kernel import Kernel - -kernel = Kernel() - -kernel_browser = kernel.browsers.create( - start_url="https://example.com", -) -``` - - ## 2. Connect to the browser diff --git a/browsers/pools/overview.mdx b/browsers/pools/overview.mdx index 470d39a..557b1f2 100644 --- a/browsers/pools/overview.mdx +++ b/browsers/pools/overview.mdx @@ -52,7 +52,6 @@ const pool = await kernel.browserPools.create({ stealth: true, headless: false, timeout_seconds: 600, - start_url: "https://example.com", viewport: { width: 1280, height: 800 @@ -73,7 +72,6 @@ pool = kernel.browser_pools.create( stealth=True, headless=False, timeout_seconds=600, - start_url="https://example.com", viewport={ "width": 1280, "height": 800 @@ -84,16 +82,6 @@ print(pool.id) ``` -### Start URL - -Pass `start_url` to have Kernel navigate newly created browsers in the pool before they become available for acquisition. Navigation is best-effort: failures do not fail pool fill, and the response records the requested `start_url` for debugging. - - -When using `start_url` with [`chrome_policy`](/browsers/pools/policy-json), `start_url` takes precedence over startup URLs configured via Chrome policies, such as `RestoreOnStartupURLs`. - -When releasing a browser with `reuse: true`, the reused browser may no longer be on the `start_url`. `start_url` applies when new browsers are created in the pool. - - ### Pool configuration options Pools can be pre-configured with options like 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. @@ -159,7 +147,6 @@ Update the pool configuration. By default, all idle browsers are discarded and r const updatedPool = await kernel.browserPools.update("my-pool", { size: 20, stealth: true, - start_url: "https://example.com", }); ``` @@ -168,7 +155,6 @@ updated_pool = kernel.browser_pools.update( "my-pool", size=20, stealth=True, - start_url="https://example.com", ) ``` @@ -177,8 +163,6 @@ updated_pool = kernel.browser_pools.update( The `size` parameter is always required when updating a pool, even if you only want to change other settings. -Set `start_url` to a new URL to change where newly created browsers in the pool start. Set `start_url` to an empty string to clear it. - By default, updating a pool discards all idle browsers and rebuilds them with the new configuration. Set `discard_all_idle: false` to keep existing idle browsers and only apply the new configuration to newly created browsers. ## Flush idle browsers diff --git a/browsers/pools/policy-json.mdx b/browsers/pools/policy-json.mdx index f83c772..1bd9c0d 100644 --- a/browsers/pools/policy-json.mdx +++ b/browsers/pools/policy-json.mdx @@ -127,10 +127,6 @@ The example above demonstrates setting a default homepage and managed bookmarks. | `BookmarkBarEnabled` | `boolean` | Shows the bookmark bar | | `ManagedBookmarks` | `array` | Pre-configured bookmarks. Supports folders via nested `children` arrays | -## Interaction with `start_url` - -If you set [`start_url`](/browsers/pools/overview#start-url) on a pool, Kernel attempts that navigation after browser startup, so it takes precedence over startup URLs configured via Chrome policies, such as `RestoreOnStartup` / `RestoreOnStartupURLs`. - ## Available policies Any policy listed in the [Chrome Enterprise policy documentation](https://chromeenterprise.google/policies/) can be used in the `chrome_policy` object. Refer to the official docs for the full list of supported policy names, types, and values. From 4e37b33b55aa8463ceecdb118a3175237b15f694 Mon Sep 17 00:00:00 2001 From: yummybomb <19238148+yummybomb@users.noreply.github.com> Date: Wed, 13 May 2026 20:44:38 +0000 Subject: [PATCH 4/6] Reference start_url in pool overview --- browsers/pools/overview.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/browsers/pools/overview.mdx b/browsers/pools/overview.mdx index 557b1f2..bec0d85 100644 --- a/browsers/pools/overview.mdx +++ b/browsers/pools/overview.mdx @@ -52,6 +52,7 @@ const pool = await kernel.browserPools.create({ stealth: true, headless: false, timeout_seconds: 600, + start_url: "https://example.com", viewport: { width: 1280, height: 800 @@ -72,6 +73,7 @@ pool = kernel.browser_pools.create( stealth=True, headless=False, timeout_seconds=600, + start_url="https://example.com", viewport={ "width": 1280, "height": 800 @@ -84,7 +86,7 @@ print(pool.id) ### Pool configuration options -Pools can be pre-configured with options like 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. +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. ## Acquire a browser From 68eae4997970a3b1852901980d01ed17503b81e5 Mon Sep 17 00:00:00 2001 From: yummybomb <19238148+yummybomb@users.noreply.github.com> Date: Wed, 13 May 2026 21:09:04 +0000 Subject: [PATCH 5/6] Document start_url with profiles --- auth/profiles.mdx | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/auth/profiles.mdx b/auth/profiles.mdx index a58277f..811c198 100644 --- a/auth/profiles.mdx +++ b/auth/profiles.mdx @@ -112,6 +112,28 @@ print("Live view:", kernel_browser2.browser_live_view_url) ``` +## Override opening existing tabs in a new session + +Profiles can restore tabs saved in the profile. Pass `start_url` with the profile to clear those restored tabs and open a specific page when the new browser starts. + + +```typescript Typescript/Javascript +const browser = await kernel.browsers.create({ + profile: { name: 'profiles-demo' }, + start_url: 'https://example.com/dashboard', +}); +``` + +```python Python +browser = await kernel.browsers.create( + profile={"name": "profiles-demo"}, + start_url="https://example.com/dashboard", +) +``` + + +The same behavior applies to browser pools configured with both a profile and start url. + ## Loading a profile into an existing browser You can load a profile into a browser after it has been created using the [update browser endpoint](https://kernel.sh/docs/api-reference/browsers/update-browser-session). From 4707c339adb3a82b0cbbe52f032db8218740b9d0 Mon Sep 17 00:00:00 2001 From: Nicholas Chen Date: Thu, 14 May 2026 14:07:31 -0400 Subject: [PATCH 6/6] Update auth/profiles.mdx Co-authored-by: Daniel Prevoznik --- auth/profiles.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/auth/profiles.mdx b/auth/profiles.mdx index 811c198..2e44aaf 100644 --- a/auth/profiles.mdx +++ b/auth/profiles.mdx @@ -114,7 +114,7 @@ print("Live view:", kernel_browser2.browser_live_view_url) ## Override opening existing tabs in a new session -Profiles can restore tabs saved in the profile. Pass `start_url` with the profile to clear those restored tabs and open a specific page when the new browser starts. +By default, Profiles restore existing tabs saved in the profile. Pass `start_url` with the profile to clear those restored tabs and open a specific page when the new browser starts. ```typescript Typescript/Javascript