From 8af4f4e41e55c582361aa9ffcb7dabb1c557b386 Mon Sep 17 00:00:00 2001 From: aylee855 <32498975+aylee855@users.noreply.github.com> Date: Fri, 22 May 2026 22:10:13 +0000 Subject: [PATCH 1/3] docs: document chrome_policy on on-demand browsers Add a new general /browsers/chrome-policy page covering chrome_policy for both on-demand sessions and reserved pools. Update create-a-browser to show the new options, and trim the pool-specific page to focus on pool-only behavior (discard_all_idle) while linking to the general reference. Co-Authored-By: Claude Opus 4.7 --- browsers/chrome-policy.mdx | 143 +++++++++++++++++++++++++++++++++ browsers/create-a-browser.mdx | 25 ++++++ browsers/pools/policy-json.mdx | 23 +----- docs.json | 1 + 4 files changed, 173 insertions(+), 19 deletions(-) create mode 100644 browsers/chrome-policy.mdx diff --git a/browsers/chrome-policy.mdx b/browsers/chrome-policy.mdx new file mode 100644 index 0000000..fbae1eb --- /dev/null +++ b/browsers/chrome-policy.mdx @@ -0,0 +1,143 @@ +--- +title: "Chrome policies" +description: "Customize Chrome behavior on Kernel browsers using Chrome enterprise policies" +--- + +Kernel browsers accept an optional `chrome_policy` object that lets you apply [Chrome enterprise policies](https://chromeenterprise.google/policies/) to the browser at launch. Use this to control startup behavior, default homepages, bookmarks, download UI, notifications, and other browser-level settings. + +`chrome_policy` is supported on: + +- [`browsers.create()`](https://kernel.sh/docs/api-reference/browsers/create-a-browser#body-chrome-policy) — on-demand browser sessions +- [`browserPools.create()`](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-chrome-policy) and [`browserPools.update()`](https://kernel.sh/docs/api-reference/browser-pools/update-a-browser-pool#body-chrome-policy) — reserved browser pools + +Keys are Chrome policy names and values are the corresponding settings. + +## On-demand browsers + +Pass `chrome_policy` when creating an on-demand browser. The policy is applied at session creation time. + + +```typescript Typescript/Javascript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); + +const kernelBrowser = await kernel.browsers.create({ + chrome_policy: { + HomepageLocation: "https://kernel.sh", + HomepageIsNewTabPage: false, + ShowHomeButton: true, + DownloadBubbleEnabled: false, + }, +}); +``` + +```python Python +from kernel import Kernel + +kernel = Kernel() + +kernel_browser = kernel.browsers.create( + chrome_policy={ + "HomepageLocation": "https://kernel.sh", + "HomepageIsNewTabPage": False, + "ShowHomeButton": True, + "DownloadBubbleEnabled": False, + }, +) +``` + + +The policy is echoed on `GET /browsers/{id}` and `GET /browsers` responses so you can verify what was applied. + +## Reserved browser pools + +Pass `chrome_policy` when [creating](/browsers/pools/overview#create-a-pool-of-reserved-browsers) or [updating](/browsers/pools/overview#update-a-pool) a pool. Every browser in the pool launches with the policy applied. See [Custom chrome policies on pools](/browsers/pools/policy-json) for the pool-specific update flow (including `discard_all_idle`). + + +```typescript Typescript/Javascript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); + +const pool = await kernel.browserPools.create({ + name: "my-configured-pool", + size: 5, + chrome_policy: { + HomepageLocation: "https://kernel.sh", + HomepageIsNewTabPage: false, + ShowHomeButton: true, + NewTabPageLocation: "https://kernel.sh/docs", + RestoreOnStartup: 4, + RestoreOnStartupURLs: ["https://kernel.sh"], + BookmarkBarEnabled: true, + ManagedBookmarks: [ + { toplevel_name: "Company Resources" }, + { name: "Dashboard", url: "https://example.com/dashboard" }, + { name: "Documentation", url: "https://example.com/docs" }, + { + name: "Tools", + children: [ + { name: "Jira Board", url: "https://example.com/jira" }, + { name: "Slack", url: "https://example.com/slack" }, + { name: "GitHub PRs", url: "https://example.com/github" }, + { name: "Runbooks", url: "https://example.com/runbooks" } + ] + } + ] + } +}); +``` + +```python Python +from kernel import Kernel + +kernel = Kernel() + +pool = kernel.browser_pools.create( + name="my-configured-pool", + size=5, + chrome_policy={ + "HomepageLocation": "https://kernel.sh", + "HomepageIsNewTabPage": False, + "ShowHomeButton": True, + "NewTabPageLocation": "https://kernel.sh/docs", + "RestoreOnStartup": 4, + "RestoreOnStartupURLs": ["https://kernel.sh"], + "BookmarkBarEnabled": True, + "ManagedBookmarks": [ + {"toplevel_name": "Company Resources"}, + {"name": "Dashboard", "url": "https://example.com/dashboard"}, + {"name": "Documentation", "url": "https://example.com/docs"}, + { + "name": "Tools", + "children": [ + {"name": "Jira Board", "url": "https://example.com/jira"}, + {"name": "Slack", "url": "https://example.com/slack"}, + {"name": "GitHub PRs", "url": "https://example.com/github"}, + {"name": "Runbooks", "url": "https://example.com/runbooks"} + ] + } + ] + } +) +``` + + +## Example policies + +| Policy | Type | Description | +| --- | --- | --- | +| `HomepageLocation` | `string` | URL loaded when clicking the home button | +| `HomepageIsNewTabPage` | `boolean` | When `false`, the home button navigates to `HomepageLocation` instead of the new tab page | +| `ShowHomeButton` | `boolean` | Shows the home button in the toolbar | +| `NewTabPageLocation` | `string` | URL shown when opening a new tab | +| `RestoreOnStartup` | `integer` | Set to `4` to open a specific list of URLs on browser startup | +| `RestoreOnStartupURLs` | `string[]` | URLs to open when the browser starts. Requires `RestoreOnStartup` set to `4` | +| `BookmarkBarEnabled` | `boolean` | Shows the bookmark bar | +| `ManagedBookmarks` | `array` | Pre-configured bookmarks. Supports folders via nested `children` arrays | +| `DownloadBubbleEnabled` | `boolean` | Controls the download bubble UI. Set to `false` to fall back to the classic download shelf | + +## 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/browsers/create-a-browser.mdx b/browsers/create-a-browser.mdx index 17071db..76537bf 100644 --- a/browsers/create-a-browser.mdx +++ b/browsers/create-a-browser.mdx @@ -35,6 +35,31 @@ print(kernel_browser.session_id) ``` +### Customizing the browser + +`browsers.create()` accepts options to configure the session at launch — for example, [`chrome_policy`](/browsers/chrome-policy) to apply [Chrome enterprise policies](https://chromeenterprise.google/policies/) and `start_url` to open a specific URL when the browser starts. + + +```typescript Typescript/Javascript +const kernelBrowser = await kernel.browsers.create({ + start_url: "https://example.com", + chrome_policy: { + HomepageLocation: "https://kernel.sh", + DownloadBubbleEnabled: false, + }, +}); +``` + +```python Python +kernel_browser = kernel.browsers.create( + start_url="https://example.com", + chrome_policy={ + "HomepageLocation": "https://kernel.sh", + "DownloadBubbleEnabled": False, + }, +) +``` + ## 2. Connect to the browser diff --git a/browsers/pools/policy-json.mdx b/browsers/pools/policy-json.mdx index 1bd9c0d..3981957 100644 --- a/browsers/pools/policy-json.mdx +++ b/browsers/pools/policy-json.mdx @@ -1,11 +1,11 @@ --- title: "custom chrome policies" -description: "Customize Chrome behavior in reserved browser pools using Chrome policies" +description: "Apply Chrome enterprise policies to every browser in a reserved pool" --- -Browser pools accept an optional [`chrome_policy`](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-chrome-policy) object that lets you apply [Chrome enterprise policies](https://chromeenterprise.google/policies/) to every browser in the pool. Use this to control startup behavior, default homepages, bookmarks, and other browser-level settings. +Browser pools accept an optional [`chrome_policy`](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-chrome-policy) object that applies [Chrome enterprise policies](https://chromeenterprise.google/policies/) to every browser in the pool. The same field is also available on on-demand browsers — see [Chrome policies](/browsers/chrome-policy) for the general reference, supported keys, and on-demand usage. -## Setting chrome policies +## Setting chrome policies on a pool Pass a `chrome_policy` object when [creating](/browsers/pools/overview#create-a-pool-of-reserved-browsers) or [updating](/browsers/pools/overview#update-a-pool) a pool. Keys are Chrome policy names and values are the corresponding settings. @@ -112,21 +112,6 @@ You can update `chrome_policy` on an existing pool. Pass `discard_all_idle: true } ``` -## Example policies - -The example above demonstrates setting a default homepage and managed bookmarks. Here's what each policy does: - -| Policy | Type | Description | -| --- | --- | --- | -| `HomepageLocation` | `string` | URL loaded when clicking the home button | -| `HomepageIsNewTabPage` | `boolean` | When `false`, the home button navigates to `HomepageLocation` instead of the new tab page | -| `ShowHomeButton` | `boolean` | Shows the home button in the toolbar | -| `NewTabPageLocation` | `string` | URL shown when opening a new tab | -| `RestoreOnStartup` | `integer` | Set to `4` to open a specific list of URLs on browser startup | -| `RestoreOnStartupURLs` | `string[]` | URLs to open when the browser starts. Requires `RestoreOnStartup` set to `4` | -| `BookmarkBarEnabled` | `boolean` | Shows the bookmark bar | -| `ManagedBookmarks` | `array` | Pre-configured bookmarks. Supports folders via nested `children` arrays | - ## 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. +See [Chrome policies](/browsers/chrome-policy#example-policies) for a reference of commonly used policy keys. Any policy listed in the [Chrome Enterprise policy documentation](https://chromeenterprise.google/policies/) can be used in the `chrome_policy` object. diff --git a/docs.json b/docs.json index ff068a1..95fd9ae 100644 --- a/docs.json +++ b/docs.json @@ -91,6 +91,7 @@ "browsers/replays", "browsers/viewport", "browsers/gpu-acceleration", + "browsers/chrome-policy", { "group": "Auth", "pages": [ From a5e62b09315f7a73a50e770ad99b5f17d243ece9 Mon Sep 17 00:00:00 2001 From: Aaron Lee Date: Fri, 22 May 2026 15:20:16 -0700 Subject: [PATCH 2/3] docs: trim pool example in chrome-policy.mdx to match on-demand length Co-Authored-By: Claude Sonnet 4.6 --- browsers/chrome-policy.mdx | 54 ++++++-------------------------------- 1 file changed, 8 insertions(+), 46 deletions(-) diff --git a/browsers/chrome-policy.mdx b/browsers/chrome-policy.mdx index fbae1eb..697c186 100644 --- a/browsers/chrome-policy.mdx +++ b/browsers/chrome-policy.mdx @@ -61,31 +61,12 @@ import Kernel from '@onkernel/sdk'; const kernel = new Kernel(); const pool = await kernel.browserPools.create({ - name: "my-configured-pool", + name: "my-pool", size: 5, chrome_policy: { - HomepageLocation: "https://kernel.sh", - HomepageIsNewTabPage: false, - ShowHomeButton: true, - NewTabPageLocation: "https://kernel.sh/docs", - RestoreOnStartup: 4, - RestoreOnStartupURLs: ["https://kernel.sh"], - BookmarkBarEnabled: true, - ManagedBookmarks: [ - { toplevel_name: "Company Resources" }, - { name: "Dashboard", url: "https://example.com/dashboard" }, - { name: "Documentation", url: "https://example.com/docs" }, - { - name: "Tools", - children: [ - { name: "Jira Board", url: "https://example.com/jira" }, - { name: "Slack", url: "https://example.com/slack" }, - { name: "GitHub PRs", url: "https://example.com/github" }, - { name: "Runbooks", url: "https://example.com/runbooks" } - ] - } - ] - } + DownloadBubbleEnabled: false, + HomepageLocation: "https://example.com", + }, }); ``` @@ -95,31 +76,12 @@ from kernel import Kernel kernel = Kernel() pool = kernel.browser_pools.create( - name="my-configured-pool", + name="my-pool", size=5, chrome_policy={ - "HomepageLocation": "https://kernel.sh", - "HomepageIsNewTabPage": False, - "ShowHomeButton": True, - "NewTabPageLocation": "https://kernel.sh/docs", - "RestoreOnStartup": 4, - "RestoreOnStartupURLs": ["https://kernel.sh"], - "BookmarkBarEnabled": True, - "ManagedBookmarks": [ - {"toplevel_name": "Company Resources"}, - {"name": "Dashboard", "url": "https://example.com/dashboard"}, - {"name": "Documentation", "url": "https://example.com/docs"}, - { - "name": "Tools", - "children": [ - {"name": "Jira Board", "url": "https://example.com/jira"}, - {"name": "Slack", "url": "https://example.com/slack"}, - {"name": "GitHub PRs", "url": "https://example.com/github"}, - {"name": "Runbooks", "url": "https://example.com/runbooks"} - ] - } - ] - } + "DownloadBubbleEnabled": False, + "HomepageLocation": "https://example.com", + }, ) ``` From 1441b9ac2cb2aa6432d4e2ecca0309d242a310f8 Mon Sep 17 00:00:00 2001 From: ehfeng <279398+ehfeng@users.noreply.github.com> Date: Fri, 22 May 2026 22:36:07 +0000 Subject: [PATCH 3/3] docs: use relative paths for chrome_policy api-reference links Absolute URLs were rendering with extra inline spacing inside the underlined link span. Relative paths render cleanly like other api-reference links in the docs. --- browsers/chrome-policy.mdx | 4 ++-- browsers/pools/policy-json.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/browsers/chrome-policy.mdx b/browsers/chrome-policy.mdx index 697c186..25fd606 100644 --- a/browsers/chrome-policy.mdx +++ b/browsers/chrome-policy.mdx @@ -7,8 +7,8 @@ Kernel browsers accept an optional `chrome_policy` object that lets you apply [C `chrome_policy` is supported on: -- [`browsers.create()`](https://kernel.sh/docs/api-reference/browsers/create-a-browser#body-chrome-policy) — on-demand browser sessions -- [`browserPools.create()`](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-chrome-policy) and [`browserPools.update()`](https://kernel.sh/docs/api-reference/browser-pools/update-a-browser-pool#body-chrome-policy) — reserved browser pools +- [`browsers.create()`](/api-reference/browsers/create-a-browser#body-chrome-policy) — on-demand browser sessions +- [`browserPools.create()`](/api-reference/browser-pools/create-a-browser-pool#body-chrome-policy) and [`browserPools.update()`](/api-reference/browser-pools/update-a-browser-pool#body-chrome-policy) — reserved browser pools Keys are Chrome policy names and values are the corresponding settings. diff --git a/browsers/pools/policy-json.mdx b/browsers/pools/policy-json.mdx index 3981957..de46dd0 100644 --- a/browsers/pools/policy-json.mdx +++ b/browsers/pools/policy-json.mdx @@ -3,7 +3,7 @@ title: "custom chrome policies" description: "Apply Chrome enterprise policies to every browser in a reserved pool" --- -Browser pools accept an optional [`chrome_policy`](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-chrome-policy) object that applies [Chrome enterprise policies](https://chromeenterprise.google/policies/) to every browser in the pool. The same field is also available on on-demand browsers — see [Chrome policies](/browsers/chrome-policy) for the general reference, supported keys, and on-demand usage. +Browser pools accept an optional [`chrome_policy`](/api-reference/browser-pools/create-a-browser-pool#body-chrome-policy) object that applies [Chrome enterprise policies](https://chromeenterprise.google/policies/) to every browser in the pool. The same field is also available on on-demand browsers — see [Chrome policies](/browsers/chrome-policy) for the general reference, supported keys, and on-demand usage. ## Setting chrome policies on a pool