Skip to content

Commit 8af4f4e

Browse files
aylee855claude
aylee855
and
claude
committed
docs: document chrome_policy on on-demand browsers
Add a new general /browsers/chrome-policy page covering chrome_policy for both on-demand sessions and reserved pools. Update create-a-browser to show the new options, and trim the pool-specific page to focus on pool-only behavior (discard_all_idle) while linking to the general reference. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent c1faa16 commit 8af4f4e

4 files changed

Lines changed: 173 additions & 19 deletions

File tree

‎browsers/chrome-policy.mdx‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: "Chrome policies"
3+
description: "Customize Chrome behavior on Kernel browsers using Chrome enterprise policies"
4+
---
5+
6+
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.
7+
8+
`chrome_policy` is supported on:
9+
10+
- [`browsers.create()`](https://kernel.sh/docs/api-reference/browsers/create-a-browser#body-chrome-policy) — on-demand browser sessions
11+
- [`browserPools.create()`](https://kernel.sh/docs/api-reference/browser-pools/create-a-browser-pool#body-chrome-policy) and [`browserPools.update()`](https://kernel.sh/docs/api-reference/browser-pools/update-a-browser-pool#body-chrome-policy) — reserved browser pools
12+
13+
Keys are Chrome policy names and values are the corresponding settings.
14+
15+
## On-demand browsers
16+
17+
Pass `chrome_policy` when creating an on-demand browser. The policy is applied at session creation time.
18+
19+
<CodeGroup>
20+
```typescript Typescript/Javascript
21+
import Kernel from '@onkernel/sdk';
22+
23+
const kernel = new Kernel();
24+
25+
const kernelBrowser = await kernel.browsers.create({
26+
chrome_policy: {
27+
HomepageLocation: "https://kernel.sh",
28+
HomepageIsNewTabPage: false,
29+
ShowHomeButton: true,
30+
DownloadBubbleEnabled: false,
31+
},
32+
});
33+
```
34+
35+
```python Python
36+
from kernel import Kernel
37+
38+
kernel = Kernel()
39+
40+
kernel_browser = kernel.browsers.create(
41+
chrome_policy={
42+
"HomepageLocation": "https://kernel.sh",
43+
"HomepageIsNewTabPage": False,
44+
"ShowHomeButton": True,
45+
"DownloadBubbleEnabled": False,
46+
},
47+
)
48+
```
49+
</CodeGroup>
50+
51+
The policy is echoed on `GET /browsers/{id}` and `GET /browsers` responses so you can verify what was applied.
52+
53+
## Reserved browser pools
54+
55+
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`).
56+
57+
<CodeGroup>
58+
```typescript Typescript/Javascript
59+
import Kernel from '@onkernel/sdk';
60+
61+
const kernel = new Kernel();
62+
63+
const pool = await kernel.browserPools.create({
64+
name: "my-configured-pool",
65+
size: 5,
66+
chrome_policy: {
67+
HomepageLocation: "https://kernel.sh",
68+
HomepageIsNewTabPage: false,
69+
ShowHomeButton: true,
70+
NewTabPageLocation: "https://kernel.sh/docs",
71+
RestoreOnStartup: 4,
72+
RestoreOnStartupURLs: ["https://kernel.sh"],
73+
BookmarkBarEnabled: true,
74+
ManagedBookmarks: [
75+
{ toplevel_name: "Company Resources" },
76+
{ name: "Dashboard", url: "https://example.com/dashboard" },
77+
{ name: "Documentation", url: "https://example.com/docs" },
78+
{
79+
name: "Tools",
80+
children: [
81+
{ name: "Jira Board", url: "https://example.com/jira" },
82+
{ name: "Slack", url: "https://example.com/slack" },
83+
{ name: "GitHub PRs", url: "https://example.com/github" },
84+
{ name: "Runbooks", url: "https://example.com/runbooks" }
85+
]
86+
}
87+
]
88+
}
89+
});
90+
```
91+
92+
```python Python
93+
from kernel import Kernel
94+
95+
kernel = Kernel()
96+
97+
pool = kernel.browser_pools.create(
98+
name="my-configured-pool",
99+
size=5,
100+
chrome_policy={
101+
"HomepageLocation": "https://kernel.sh",
102+
"HomepageIsNewTabPage": False,
103+
"ShowHomeButton": True,
104+
"NewTabPageLocation": "https://kernel.sh/docs",
105+
"RestoreOnStartup": 4,
106+
"RestoreOnStartupURLs": ["https://kernel.sh"],
107+
"BookmarkBarEnabled": True,
108+
"ManagedBookmarks": [
109+
{"toplevel_name": "Company Resources"},
110+
{"name": "Dashboard", "url": "https://example.com/dashboard"},
111+
{"name": "Documentation", "url": "https://example.com/docs"},
112+
{
113+
"name": "Tools",
114+
"children": [
115+
{"name": "Jira Board", "url": "https://example.com/jira"},
116+
{"name": "Slack", "url": "https://example.com/slack"},
117+
{"name": "GitHub PRs", "url": "https://example.com/github"},
118+
{"name": "Runbooks", "url": "https://example.com/runbooks"}
119+
]
120+
}
121+
]
122+
}
123+
)
124+
```
125+
</CodeGroup>
126+
127+
## Example policies
128+
129+
| Policy | Type | Description |
130+
| --- | --- | --- |
131+
| `HomepageLocation` | `string` | URL loaded when clicking the home button |
132+
| `HomepageIsNewTabPage` | `boolean` | When `false`, the home button navigates to `HomepageLocation` instead of the new tab page |
133+
| `ShowHomeButton` | `boolean` | Shows the home button in the toolbar |
134+
| `NewTabPageLocation` | `string` | URL shown when opening a new tab |
135+
| `RestoreOnStartup` | `integer` | Set to `4` to open a specific list of URLs on browser startup |
136+
| `RestoreOnStartupURLs` | `string[]` | URLs to open when the browser starts. Requires `RestoreOnStartup` set to `4` |
137+
| `BookmarkBarEnabled` | `boolean` | Shows the bookmark bar |
138+
| `ManagedBookmarks` | `array` | Pre-configured bookmarks. Supports folders via nested `children` arrays |
139+
| `DownloadBubbleEnabled` | `boolean` | Controls the download bubble UI. Set to `false` to fall back to the classic download shelf |
140+
141+
## Available policies
142+
143+
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.

‎browsers/create-a-browser.mdx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,31 @@ print(kernel_browser.session_id)
3535
```
3636
</CodeGroup>
3737

38+
### Customizing the browser
39+
40+
`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.
41+
42+
<CodeGroup>
43+
```typescript Typescript/Javascript
44+
const kernelBrowser = await kernel.browsers.create({
45+
start_url: "https://example.com",
46+
chrome_policy: {
47+
HomepageLocation: "https://kernel.sh",
48+
DownloadBubbleEnabled: false,
49+
},
50+
});
51+
```
52+
53+
```python Python
54+
kernel_browser = kernel.browsers.create(
55+
start_url="https://example.com",
56+
chrome_policy={
57+
"HomepageLocation": "https://kernel.sh",
58+
"DownloadBubbleEnabled": False,
59+
},
60+
)
61+
```
62+
</CodeGroup>
3863

3964
## 2. Connect to the browser
4065

‎browsers/pools/policy-json.mdx‎

Lines changed: 4 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
22
title: "custom chrome policies"
3-
description: "Customize Chrome behavior in reserved browser pools using Chrome policies"
3+
description: "Apply Chrome enterprise policies to every browser in a reserved pool"
44
---
55

6-
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.
6+
Browser pools accept an optional [`chrome_policy`](https://kernel.sh/docs/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.
77

8-
## Setting chrome policies
8+
## Setting chrome policies on a pool
99

1010
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.
1111

@@ -112,21 +112,6 @@ You can update `chrome_policy` on an existing pool. Pass `discard_all_idle: true
112112
}
113113
```
114114

115-
## Example policies
116-
117-
The example above demonstrates setting a default homepage and managed bookmarks. Here's what each policy does:
118-
119-
| Policy | Type | Description |
120-
| --- | --- | --- |
121-
| `HomepageLocation` | `string` | URL loaded when clicking the home button |
122-
| `HomepageIsNewTabPage` | `boolean` | When `false`, the home button navigates to `HomepageLocation` instead of the new tab page |
123-
| `ShowHomeButton` | `boolean` | Shows the home button in the toolbar |
124-
| `NewTabPageLocation` | `string` | URL shown when opening a new tab |
125-
| `RestoreOnStartup` | `integer` | Set to `4` to open a specific list of URLs on browser startup |
126-
| `RestoreOnStartupURLs` | `string[]` | URLs to open when the browser starts. Requires `RestoreOnStartup` set to `4` |
127-
| `BookmarkBarEnabled` | `boolean` | Shows the bookmark bar |
128-
| `ManagedBookmarks` | `array` | Pre-configured bookmarks. Supports folders via nested `children` arrays |
129-
130115
## Available policies
131116

132-
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.
117+
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.

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@
9191
"browsers/replays",
9292
"browsers/viewport",
9393
"browsers/gpu-acceleration",
94+
"browsers/chrome-policy",
9495
{
9596
"group": "Auth",
9697
"pages": [

0 commit comments

Comments
 (0)