Skip to content

Commit 578fb1f

Browse files
hiroTamadagithub-actions[bot]dprevoznik
authored
Configurable viewport docs (#76)
* Configurable viewport docs * Make viewport optional * moar * moar * moar * moar * docs: update code samples from OpenAPI * Update browser-use.mdx Added informational note about Browser Use's configuration options. * moar --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Daniel Prevoznik <danny@onkernel.com>
1 parent 0c3622c commit 578fb1f

File tree

5 files changed

+217
-4
lines changed

5 files changed

+217
-4
lines changed

‎browsers/viewport.mdx‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
title: "Viewports"
3+
description: "Configure browser viewport size and refresh rate for your automations"
4+
---
5+
6+
Kernel browsers allow you to configure the viewport size and refresh rate when creating a browser session. The viewport configuration determines the initial browser window dimensions and display refresh rate. The refresh rate can be explicitly specified or automatically determined based on the width and height if they match a supported configuration.
7+
8+
## Setting viewport configuration
9+
10+
You can configure the viewport when creating a browser by specifying the `viewport` parameter with `width` and `height`. The `refresh_rate` is optional and will be automatically determined from the dimensions if they match a supported configuration:
11+
12+
<CodeGroup>
13+
14+
```typescript Typescript/Javascript
15+
// Explicitly specify refresh rate
16+
const kernelBrowser = await kernel.browsers.create({
17+
viewport: {
18+
width: 1920,
19+
height: 1080,
20+
refresh_rate: 25
21+
}
22+
});
23+
24+
// Auto-determine refresh rate from dimensions (25Hz for 1920x1080)
25+
const kernelBrowserAuto = await kernel.browsers.create({
26+
viewport: {
27+
width: 1920,
28+
height: 1080
29+
}
30+
});
31+
```
32+
33+
```python Python
34+
# Explicitly specify refresh rate
35+
kernel_browser = client.browsers.create(
36+
viewport={
37+
"width": 1920,
38+
"height": 1080,
39+
"refresh_rate": 25
40+
}
41+
)
42+
43+
# Auto-determine refresh rate from dimensions (25Hz for 1920x1080)
44+
kernel_browser_auto = client.browsers.create(
45+
viewport={
46+
"width": 1920,
47+
"height": 1080
48+
}
49+
)
50+
```
51+
52+
</CodeGroup>
53+
54+
## Supported viewport configurations
55+
56+
Kernel supports specific viewport configurations. The server will reject unsupported combinations. When you provide width and height without specifying refresh_rate, it will be automatically determined if the dimensions match one of the supported resolutions exactly. The following resolutions are supported:
57+
58+
| Resolution | Width | Height | Refresh Rate |
59+
|------------|-------|--------|--------------|
60+
| QHD | 2560 | 1440 | 10 Hz |
61+
| Full HD | 1920 | 1080 | 25 Hz |
62+
| WUXGA | 1920 | 1200 | 25 Hz |
63+
| WXGA+ | 1440 | 900 | 25 Hz |
64+
| XGA | 1024 | 768 | 60 Hz |
65+
66+
<Warning>
67+
Higher resolutions may affect the responsiveness of [live view](/browsers/live-view) browser sessions.
68+
</Warning>
69+
70+
## Example configurations
71+
72+
<CodeGroup>
73+
74+
```typescript Typescript/Javascript
75+
// Full HD (1920x1080) at 25Hz - explicit refresh rate
76+
const fullHD = await kernel.browsers.create({
77+
viewport: {
78+
width: 1920,
79+
height: 1080,
80+
refresh_rate: 25
81+
}
82+
});
83+
84+
// Full HD (1920x1080) - auto-determined 25Hz
85+
const fullHDAuto = await kernel.browsers.create({
86+
viewport: {
87+
width: 1920,
88+
height: 1080
89+
}
90+
});
91+
92+
// QHD (2560x1440) - auto-determined 10Hz
93+
// Note: May affect live view responsiveness
94+
const qhd = await kernel.browsers.create({
95+
viewport: {
96+
width: 2560,
97+
height: 1440
98+
}
99+
});
100+
101+
// XGA (1024x768) - auto-determined 60Hz (Default configuration)
102+
const xga = await kernel.browsers.create({
103+
viewport: {
104+
width: 1024,
105+
height: 768
106+
}
107+
});
108+
109+
// WUXGA (1920x1200) at 25Hz - explicit refresh rate
110+
const wuxga = await kernel.browsers.create({
111+
viewport: {
112+
width: 1920,
113+
height: 1200,
114+
refresh_rate: 25
115+
}
116+
});
117+
```
118+
119+
```python Python
120+
# Full HD (1920x1080) at 25Hz - explicit refresh rate
121+
full_hd = await client.browsers.create(
122+
viewport={
123+
"width": 1920,
124+
"height": 1080,
125+
"refresh_rate": 25
126+
}
127+
)
128+
129+
# Full HD (1920x1080) - auto-determined 25Hz
130+
full_hd_auto = await client.browsers.create(
131+
viewport={
132+
"width": 1920,
133+
"height": 1080
134+
}
135+
)
136+
137+
# QHD (2560x1440) - auto-determined 10Hz
138+
# Note: May affect live view responsiveness
139+
qhd = await client.browsers.create(
140+
viewport={
141+
"width": 2560,
142+
"height": 1440
143+
}
144+
)
145+
146+
# XGA (1024x768) - auto-determined 60Hz (Default configuration)
147+
xga = await client.browsers.create(
148+
viewport={
149+
"width": 1024,
150+
"height": 768
151+
}
152+
)
153+
154+
# WUXGA (1920x1200) at 25Hz - explicit refresh rate
155+
wuxga = await client.browsers.create(
156+
viewport={
157+
"width": 1920,
158+
"height": 1200,
159+
"refresh_rate": 25
160+
}
161+
)
162+
```
163+
164+
</CodeGroup>
165+
166+
## Default viewport
167+
168+
If the `viewport` parameter is omitted when creating a browser, the default configuration is typically 1024x768 at 60Hz.
169+
170+
<CodeGroup>
171+
172+
```typescript Typescript/Javascript
173+
// Uses default viewport (1024x768@60Hz)
174+
const defaultViewport = await kernel.browsers.create();
175+
```
176+
177+
```python Python
178+
# Uses default viewport (1024x768@60Hz)
179+
default_viewport = await client.browsers.create()
180+
```
181+
182+
</CodeGroup>
183+
184+
## Viewport constraints
185+
186+
Only the specific viewport configurations listed in the [supported configurations table](#supported-viewport-configurations) above are supported:
187+
- **2560x1440** (QHD) at 10 Hz
188+
- **1920x1080** (Full HD) at 25 Hz
189+
- **1920x1200** (WUXGA) at 25 Hz
190+
- **1440x900** (WXGA+) at 25 Hz
191+
- **1024x768** (XGA) at 60 Hz
192+
193+
When specifying a viewport:
194+
- **Width** and **Height** are required and must match one of the supported configurations exactly
195+
- **Refresh Rate** is optional - if omitted, it will be automatically determined from the width and height combination
196+
197+
<Warning>
198+
The server will reject any viewport configuration that doesn't exactly match one of the supported combinations listed above.
199+
</Warning>
200+
201+
## Considerations
202+
203+
- The viewport configuration is set when the browser is created and applies to the initial browser window
204+
- Higher resolutions (like 2560x1440) may impact the performance and responsiveness of live view sessions
205+
- The viewport size affects how websites render, especially those with responsive designs
206+
- Screenshots taken from the browser will match the configured viewport dimensions
207+
- In [headless mode](/browsers/headless), the viewport configuration still applies for rendering and screenshots

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757
"pages": [
5858
"browsers/create-a-browser",
5959
"browsers/headless",
60+
"browsers/viewport",
6061
"browsers/standby",
6162
"browsers/persistence",
6263
"browsers/profiles",

‎info/pricing.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ With Kernel, you only pay for what you use and nothing more. Our goal is to be c
1414
| Free usage credits / mo | $5 | $50 | Custom |
1515
| Browser persistence | ✅ | ✅ | ✅ |
1616
| Browser live view & logs | ✅ | ✅ | ✅ |
17+
| Browser viewports | ✅ | ✅ | ✅ |
1718
| Browser replays | ❌ | ✅ | ✅ |
1819
| Browser profiles | ❌ | ✅ | ✅ |
1920
| File uploads & downloads | ❌ | ✅ | ✅ |

‎integrations/browser-use.mdx‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,12 +38,16 @@ Replace your existing Browser initialization to use Kernel's CDP URL and display
3838
browser = Browser(
3939
cdp_url=kernel_browser.cdp_ws_url,
4040
headless=False,
41-
window_size={'width': 1024, 'height': 786},
42-
viewport={'width': 1024, 'height': 786},
41+
window_size={'width': 1024, 'height': 768},
42+
viewport={'width': 1024, 'height': 768},
4343
device_scale_factor=1.0
4444
)
4545
```
4646

47+
<Info>
48+
Browser Use supports a wide range of browser configuration parameters. See the full list in the <a href="https://docs.browser-use.com/customize/browser/all-parameters">Browser Use docs</a>. When running on Kernel, remember that browsers must use one of Kernel’s supported viewport sizes and refresh rates—see <a href="/browsers/viewport">Viewports</a> for the supported configurations.
49+
</Info>
50+
4751
### 4. Create and run your agent
4852

4953
Use your existing Agent setup with the Kernel-powered browser:

‎snippets/openapi/post-browsers-id-extensions.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ const client = new Kernel({
66
apiKey: 'My API Key',
77
});
88

9-
await client.browsers.uploadExtensions('id', {
9+
await client.browsers.loadExtensions('id', {
1010
extensions: [{ name: 'name', zip_file: fs.createReadStream('path/to/file') }],
1111
});
1212
```
@@ -18,7 +18,7 @@ from kernel import Kernel
1818
client = Kernel(
1919
api_key="My API Key",
2020
)
21-
client.browsers.upload_extensions(
21+
client.browsers.load_extensions(
2222
id="id",
2323
extensions=[{
2424
"name": "name",

0 commit comments

Comments
 (0)