Custom Chrome Policies

chrome_policy is an optional object that applies Chrome enterprise policies to a browser. It works on both individual on-demand browsers (browsers.create()) and browser pools, where it applies to every browser in the pool. Use it to control startup behavior, default homepages, bookmarks, and other browser-level settings. Keys are Chrome policy names and values are the corresponding settings. The same policies and value types apply on both paths. Kernel-managed policies (extensions, proxy, and CDP/automation) are rejected, and the serialized payload is capped at 5 MiB.

Setting chrome policies on a pool

Pass a chrome_policy object when creating or updating a pool.

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

from kernel import Kernel

kernel = Kernel()

pool = kernel.browser_pools.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"}
                ]
            }
        ]
    }
)

package main

import (
	"context"

	"github.com/kernel/kernel-go-sdk"
)

func main() {
	ctx := context.Background()
	client := kernel.NewClient()

	pool, err := client.BrowserPools.New(ctx, kernel.BrowserPoolNewParams{
		Name: kernel.String("my-configured-pool"),
		Size: 5,
		ChromePolicy: map[string]any{
			"HomepageLocation":     "https://kernel.sh",
			"HomepageIsNewTabPage": false,
			"ShowHomeButton":       true,
			"NewTabPageLocation":   "https://kernel.sh/docs",
			"RestoreOnStartup":     4,
			"RestoreOnStartupURLs": []string{"https://kernel.sh"},
			"BookmarkBarEnabled":   true,
			"ManagedBookmarks": []map[string]any{
				{"toplevel_name": "Company Resources"},
				{"name": "Dashboard", "url": "https://example.com/dashboard"},
				{"name": "Documentation", "url": "https://example.com/docs"},
				{
					"name": "Tools",
					"children": []map[string]string{
						{"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"},
					},
				},
			},
		},
	})
	if err != nil {
		panic(err)
	}
	_ = pool
}

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

The examples below use browsers.create(), but the same policies apply when set on a pool.

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,
    }
)

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const browser = await 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,
    }
)

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

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

Block DevTools and page source

DevTools hands anyone who can reach a browser a console on the page, plus network logs, cookies, and local storage. When you expose a session through live view, or run agent code you don’t fully trust, block the URLs DevTools loads from:

from kernel import Kernel

kernel = Kernel()

browser = kernel.browsers.create(
    chrome_policy={
        "URLBlocklist": ["devtools://*", "chrome://inspect", "view-source:*"],
    }
)

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const browser = await kernel.browsers.create({
  chrome_policy: {
    URLBlocklist: ["devtools://*", "chrome://inspect", "view-source:*"],
  },
});

To lock a browser to an approved set of URLs, block everything with URLBlocklist and then allow back only the URLs you want with URLAllowlist. Entries match a whole domain (chatgpt.com) or a specific path (en.wikipedia.org/wiki/Cat), and more specific entries take precedence. This gates top-level navigation, so any other URL returns ERR_BLOCKED_BY_ADMINISTRATOR; it does not block resources or API calls a permitted page loads from other origins.

from kernel import Kernel

kernel = Kernel()

browser = kernel.browsers.create(
    chrome_policy={
        "URLBlocklist": ["*"],
        "URLAllowlist": ["chatgpt.com", "en.wikipedia.org/wiki/Cat"],
    }
)

import Kernel from '@onkernel/sdk';

const kernel = new Kernel();

const browser = await kernel.browsers.create({
  chrome_policy: {
    URLBlocklist: ["*"],
    URLAllowlist: ["chatgpt.com", "en.wikipedia.org/wiki/Cat"],
  },
});

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.

Overview

Working with your browser

deploying your agent

Agent Skills

Integrations

Migrations

Community

Info

Custom Chrome Policies

Setting chrome policies on a pool

Updating policies on an existing pool

Example policies

Common use cases

Allow pop-ups

Control file download behavior

Block DevTools and page source

Restrict navigation to specific URLs

Available policies

​Setting chrome policies on a pool

​Updating policies on an existing pool

​Example policies

​Common use cases

​Allow pop-ups

​Control file download behavior

​Block DevTools and page source

​Restrict navigation to specific URLs

​Available policies

Setting chrome policies on a pool

Updating policies on an existing pool

Example policies

Common use cases

Allow pop-ups

Control file download behavior

Block DevTools and page source

Restrict navigation to specific URLs

Available policies