diff --git a/browsers/pools/managing-browsers.mdx b/browsers/pools/managing-browsers.mdx new file mode 100644 index 0000000..b7be6c2 --- /dev/null +++ b/browsers/pools/managing-browsers.mdx @@ -0,0 +1,82 @@ +--- +title: "Managing Browsers" +description: "Customize Chrome behavior in reserved browser pools using Chrome policies" +--- + +Browser pools accept an optional `chrome_policy` object that lets you apply [Chrome enterprise policy settings](https://chromeenterprise.google/policies/) to every browser in the pool. Use this to control startup behavior, default homepages, new tab pages, and other browser-level preferences. + +## Setting Chrome policies + +Pass a `chrome_policy` object when creating a pool. The keys are Chrome policy names and the values are the corresponding policy settings. + + +```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: { + HomepageIsNewTabPage: false, + HomepageLocation: "https://kernel.sh", + NewTabPageLocation: "https://kernel.com/docs", + RestoreOnStartup: 4, + RestoreOnStartupURLs: [ + "https://kernel.sh" + ] + } +}); +``` + +```python Python +from kernel import Kernel + +kernel = Kernel() + +pool = kernel.browser_pools.create( + name="my-configured-pool", + size=5, + chrome_policy={ + "HomepageIsNewTabPage": False, + "HomepageLocation": "https://kernel.sh", + "NewTabPageLocation": "https://kernel.com/docs", + "RestoreOnStartup": 4, + "RestoreOnStartupURLs": [ + "https://kernel.sh" + ] + } +) +``` + + +You can also set `chrome_policy` when [updating a pool](/browsers/pools/overview#update-a-pool). By default, idle browsers are discarded and rebuilt with the new configuration. + +## Example: setting a default homepage + +The following configuration opens `https://kernel.sh` on startup, sets the Kernel docs as the new tab page, and configures the home button to navigate to `https://kernel.sh`: + +```json +{ + "HomepageIsNewTabPage": false, + "HomepageLocation": "https://kernel.sh", + "NewTabPageLocation": "https://kernel.com/docs", + "RestoreOnStartup": 4, + "RestoreOnStartupURLs": [ + "https://kernel.sh" + ] +} +``` + +| Policy | Type | Description | +| --- | --- | --- | +| `HomepageIsNewTabPage` | `boolean` | When `false`, the home button navigates to `HomepageLocation` instead of the new tab page. | +| `HomepageLocation` | `string` | URL loaded when clicking the home button. | +| `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`. | + +## Available policies + +Any policy listed in the [Chrome Enterprise policy documentation](https://chromeenterprise.google/policies/) can be passed in the `chrome_policy` object. Refer to the official docs for the full list of supported policy names, types, and values. diff --git a/docs.json b/docs.json index 8e8fd33..aea18d9 100644 --- a/docs.json +++ b/docs.json @@ -137,6 +137,7 @@ "group": "Reserved Browsers", "pages": [ "browsers/pools/overview", + "browsers/pools/managing-browsers", "browsers/pools/scaling", "browsers/pools/faq" ]