Custom Chrome Policies

Browser pools accept an optional chrome_policy object that lets you apply Chrome enterprise policies to every browser in the pool. Use this to control startup behavior, default homepages, bookmarks, and other browser-level settings.

Setting chrome policies

Pass a chrome_policy object when creating or updating a pool. Keys are Chrome policy names and values are the corresponding settings.

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" }
        ]
      }
    ]
  }
});

Updating policies on an existing pool

You can update chrome_policy on an existing pool. Pass discard_all_idle: true to immediately replace all idle browsers with the new policy configuration.

{
  "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"}
        ]
      }
    ]
  },
  "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

Common use cases

chrome_policy is also accepted directly on browsers.create() when you don't need a reserved pool. The examples below use that path.

Allow pop-ups

Chrome's default blocks pop-ups, which breaks sites that open download dialogs or OAuth windows in a new window. Set DefaultPopupsSetting to 1 to allow them (2 blocks).

from kernel import Kernel

kernel = Kernel()

browser = kernel.browsers.create(
    chrome_policy={
        "DefaultPopupsSetting": 1,
    }
)

Control file download behavior

When automating file downloads that trigger permission prompts, combine DefaultPopupsSetting: 1 with DownloadRestrictions: 0 to allow all downloads.

from kernel import Kernel

kernel = Kernel()

browser = kernel.browsers.create(
    chrome_policy={
        "DefaultPopupsSetting": 1,
        "DownloadRestrictions": 0,
    }
)

Available policies

Any policy listed in the Chrome Enterprise policy documentation can be used in the chrome_policy object. Refer to the official docs for the full list of supported policy names, types, and values.