docs: document chrome_policy on on-demand browsers #377
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,105 @@ | ||
| --- | ||
| 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()`](/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. | ||
|
|
||
| ## On-demand browsers | ||
|
|
||
| Pass `chrome_policy` when creating an on-demand browser. The policy is applied at session creation time. | ||
|
|
||
| <CodeGroup> | ||
| ```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, | ||
| }, | ||
| ) | ||
| ``` | ||
| </CodeGroup> | ||
|
|
||
| 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`). | ||
|
|
||
| <CodeGroup> | ||
| ```typescript Typescript/Javascript | ||
| import Kernel from '@onkernel/sdk'; | ||
|
|
||
| const kernel = new Kernel(); | ||
|
|
||
| const pool = await kernel.browserPools.create({ | ||
| name: "my-pool", | ||
| size: 5, | ||
| chrome_policy: { | ||
| DownloadBubbleEnabled: false, | ||
| HomepageLocation: "https://example.com", | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| ```python Python | ||
| from kernel import Kernel | ||
|
|
||
| kernel = Kernel() | ||
|
|
||
| pool = kernel.browser_pools.create( | ||
| name="my-pool", | ||
| size=5, | ||
| chrome_policy={ | ||
| "DownloadBubbleEnabled": False, | ||
| "HomepageLocation": "https://example.com", | ||
| }, | ||
| ) | ||
| ``` | ||
| </CodeGroup> | ||
|
|
||
| ## 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 | | ||
|
There was a problem hiding this comment. Deprecated Chrome policy documented with incorrect behaviorMedium Severity
Additional Locations (2)  Reviewed by Cursor Bugbot for commit a5e62b0. Configure here. |
||
|
|
||
| ## 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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Relative
/api-reference/links will break CI checksHigh Severity
All
/api-reference/...links in the newbrowsers/chrome-policy.mdxpage (lines 10–11) and the updatedbrowsers/pools/policy-json.mdx(line 6) use relative paths. API reference pages are auto-generated from a remote OpenAPI spec and don't exist locally, so relative links will fail themint broken-linksCI check. These need to be absolute URLs (e.g.https://kernel.sh/docs/api-reference/...). Notably,policy-json.mdxpreviously had the correct absolute URL and this PR regressed it to a relative one.Additional Locations (1)
browsers/pools/policy-json.mdx#L5-L6Triggered by learned rule: Use absolute URLs for /api-reference/ links
Reviewed by Cursor Bugbot for commit 1441b9a. Configure here.