Custom Chrome Policies

Customize Chrome behavior in reserved browser pools using 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.

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

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).

Python

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.

Python

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.