diff --git a/browsers/chrome-policy.mdx b/browsers/chrome-policy.mdx new file mode 100644 index 0000000..25fd606 --- /dev/null +++ b/browsers/chrome-policy.mdx @@ -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. + + +```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-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", + }, +) +``` + + +## 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..de46dd0 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`](/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": [