From d719d69eef0194fd2e65aec5b00378a0b831ebef Mon Sep 17 00:00:00 2001 From: Hiro Tamada Date: Fri, 10 Oct 2025 15:55:46 -0400 Subject: [PATCH 1/9] Configurable viewport docs --- browsers/viewport.mdx | 169 ++++++++++++++++++++++++++++++++++++++++++ docs.json | 1 + 2 files changed, 170 insertions(+) create mode 100644 browsers/viewport.mdx diff --git a/browsers/viewport.mdx b/browsers/viewport.mdx new file mode 100644 index 0000000..34f372d --- /dev/null +++ b/browsers/viewport.mdx @@ -0,0 +1,169 @@ +--- +title: "Viewport Configuration" +description: "Configure browser viewport size and refresh rate for your automations" +--- + +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. + +## Setting viewport configuration + +You can configure the viewport when creating a browser by specifying the `viewport` parameter with `width`, `height`, and `refresh_rate`: + + + +```typescript Typescript/Javascript +const kernelBrowser = await kernel.browsers.create({ + viewport: { + width: 1920, + height: 1080, + refresh_rate: 25 + } +}); +``` + +```python Python +kernel_browser = client.browsers.create( + viewport={ + "width": 1920, + "height": 1080, + "refresh_rate": 25 + } +) +``` + + + +## Supported viewport configurations + +Kernel supports specific viewport configurations. The server will reject unsupported combinations. The following resolutions are supported: + +| Resolution | Width | Height | Refresh Rate | +|------------|-------|--------|--------------| +| QHD | 2560 | 1440 | 10 Hz | +| Full HD | 1920 | 1080 | 25 Hz | +| WUXGA | 1920 | 1200 | 25 Hz | +| WXGA+ | 1440 | 900 | 25 Hz | +| XGA | 1024 | 768 | 60 Hz | + + +Higher resolutions may affect the responsiveness of [live view](/browsers/live-view) browser sessions. + + +## Example configurations + + + +```typescript Typescript/Javascript +// Full HD (1920x1080) at 25Hz +const fullHD = await kernel.browsers.create({ + viewport: { + width: 1920, + height: 1080, + refresh_rate: 25 + } +}); + +// QHD (2560x1440) at 10Hz - Note: May affect live view responsiveness +const qhd = await kernel.browsers.create({ + viewport: { + width: 2560, + height: 1440, + refresh_rate: 10 + } +}); + +// XGA (1024x768) at 60Hz - Default configuration +const xga = await kernel.browsers.create({ + viewport: { + width: 1024, + height: 768, + refresh_rate: 60 + } +}); + +// WUXGA (1920x1200) at 25Hz +const wuxga = await kernel.browsers.create({ + viewport: { + width: 1920, + height: 1200, + refresh_rate: 25 + } +}); +``` + +```python Python +# Full HD (1920x1080) at 25Hz +full_hd = await client.browsers.create( + viewport={ + "width": 1920, + "height": 1080, + "refresh_rate": 25 + } +) + +# QHD (2560x1440) at 10Hz - Note: May affect live view responsiveness +qhd = await client.browsers.create( + viewport={ + "width": 2560, + "height": 1440, + "refresh_rate": 10 + } +) + +# XGA (1024x768) at 60Hz - Default configuration +xga = await client.browsers.create( + viewport={ + "width": 1024, + "height": 768, + "refresh_rate": 60 + } +) + +# WUXGA (1920x1200) at 25Hz +wuxga = await client.browsers.create( + viewport={ + "width": 1920, + "height": 1200, + "refresh_rate": 25 + } +) +``` + + + +## Default viewport + +If the `viewport` parameter is omitted when creating a browser, the default configuration is typically 1024x768 at 60Hz. + + + +```typescript Typescript/Javascript +// Uses default viewport (1024x768@60Hz) +const defaultViewport = await kernel.browsers.create(); +``` + +```python Python +# Uses default viewport (1024x768@60Hz) +default_viewport = await client.browsers.create() +``` + + + +## Viewport constraints + +The viewport configuration has the following constraints: +- **Width**: Minimum 320px, Maximum 7680px +- **Height**: Minimum 240px, Maximum 4320px +- **Refresh Rate**: Must match the supported configurations listed above + + +While the API accepts width and height values within the min/max ranges, only the specific resolution and refresh rate combinations listed in the supported configurations table are actually supported. The server will reject any unsupported combinations. + + +## Considerations + +- The viewport configuration is set when the browser is created and applies to the initial browser window +- Higher resolutions (like 2560x1440) may impact the performance and responsiveness of live view sessions +- The viewport size affects how websites render, especially those with responsive designs +- Screenshots taken from the browser will match the configured viewport dimensions +- In [headless mode](/browsers/headless), the viewport configuration still applies for rendering and screenshots diff --git a/docs.json b/docs.json index e3147b3..e1db215 100644 --- a/docs.json +++ b/docs.json @@ -57,6 +57,7 @@ "pages": [ "browsers/create-a-browser", "browsers/headless", + "browsers/viewport", "browsers/standby", "browsers/persistence", "browsers/profiles", From 2c577b1951c4a9cd96cd8278fc2d356da05a4072 Mon Sep 17 00:00:00 2001 From: Hiro Tamada Date: Mon, 13 Oct 2025 10:46:58 -0400 Subject: [PATCH 2/9] Make viewport optional --- browsers/viewport.mdx | 78 ++++++++++++++++++++++++++++++------------- 1 file changed, 55 insertions(+), 23 deletions(-) diff --git a/browsers/viewport.mdx b/browsers/viewport.mdx index 34f372d..6959019 100644 --- a/browsers/viewport.mdx +++ b/browsers/viewport.mdx @@ -3,15 +3,16 @@ title: "Viewport Configuration" description: "Configure browser viewport size and refresh rate for your automations" --- -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. +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. ## Setting viewport configuration -You can configure the viewport when creating a browser by specifying the `viewport` parameter with `width`, `height`, and `refresh_rate`: +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: ```typescript Typescript/Javascript +// Explicitly specify refresh rate const kernelBrowser = await kernel.browsers.create({ viewport: { width: 1920, @@ -19,9 +20,18 @@ const kernelBrowser = await kernel.browsers.create({ refresh_rate: 25 } }); + +// Auto-determine refresh rate from dimensions (25Hz for 1920x1080) +const kernelBrowserAuto = await kernel.browsers.create({ + viewport: { + width: 1920, + height: 1080 + } +}); ``` ```python Python +# Explicitly specify refresh rate kernel_browser = client.browsers.create( viewport={ "width": 1920, @@ -29,13 +39,21 @@ kernel_browser = client.browsers.create( "refresh_rate": 25 } ) + +# Auto-determine refresh rate from dimensions (25Hz for 1920x1080) +kernel_browser_auto = client.browsers.create( + viewport={ + "width": 1920, + "height": 1080 + } +) ``` ## Supported viewport configurations -Kernel supports specific viewport configurations. The server will reject unsupported combinations. The following resolutions are supported: +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: | Resolution | Width | Height | Refresh Rate | |------------|-------|--------|--------------| @@ -54,7 +72,7 @@ Higher resolutions may affect the responsiveness of [live view](/browsers/live-v ```typescript Typescript/Javascript -// Full HD (1920x1080) at 25Hz +// Full HD (1920x1080) at 25Hz - explicit refresh rate const fullHD = await kernel.browsers.create({ viewport: { width: 1920, @@ -63,25 +81,32 @@ const fullHD = await kernel.browsers.create({ } }); -// QHD (2560x1440) at 10Hz - Note: May affect live view responsiveness +// Full HD (1920x1080) - auto-determined 25Hz +const fullHDAuto = await kernel.browsers.create({ + viewport: { + width: 1920, + height: 1080 + } +}); + +// QHD (2560x1440) - auto-determined 10Hz +// Note: May affect live view responsiveness const qhd = await kernel.browsers.create({ viewport: { width: 2560, - height: 1440, - refresh_rate: 10 + height: 1440 } }); -// XGA (1024x768) at 60Hz - Default configuration +// XGA (1024x768) - auto-determined 60Hz (Default configuration) const xga = await kernel.browsers.create({ viewport: { width: 1024, - height: 768, - refresh_rate: 60 + height: 768 } }); -// WUXGA (1920x1200) at 25Hz +// WUXGA (1920x1200) at 25Hz - explicit refresh rate const wuxga = await kernel.browsers.create({ viewport: { width: 1920, @@ -92,7 +117,7 @@ const wuxga = await kernel.browsers.create({ ``` ```python Python -# Full HD (1920x1080) at 25Hz +# Full HD (1920x1080) at 25Hz - explicit refresh rate full_hd = await client.browsers.create( viewport={ "width": 1920, @@ -101,25 +126,32 @@ full_hd = await client.browsers.create( } ) -# QHD (2560x1440) at 10Hz - Note: May affect live view responsiveness +# Full HD (1920x1080) - auto-determined 25Hz +full_hd_auto = await client.browsers.create( + viewport={ + "width": 1920, + "height": 1080 + } +) + +# QHD (2560x1440) - auto-determined 10Hz +# Note: May affect live view responsiveness qhd = await client.browsers.create( viewport={ "width": 2560, - "height": 1440, - "refresh_rate": 10 + "height": 1440 } ) -# XGA (1024x768) at 60Hz - Default configuration +# XGA (1024x768) - auto-determined 60Hz (Default configuration) xga = await client.browsers.create( viewport={ "width": 1024, - "height": 768, - "refresh_rate": 60 + "height": 768 } ) -# WUXGA (1920x1200) at 25Hz +# WUXGA (1920x1200) at 25Hz - explicit refresh rate wuxga = await client.browsers.create( viewport={ "width": 1920, @@ -152,12 +184,12 @@ default_viewport = await client.browsers.create() ## Viewport constraints The viewport configuration has the following constraints: -- **Width**: Minimum 320px, Maximum 7680px -- **Height**: Minimum 240px, Maximum 4320px -- **Refresh Rate**: Must match the supported configurations listed above +- **Width** (required): Minimum 320px, Maximum 7680px +- **Height** (required): Minimum 240px, Maximum 4320px +- **Refresh Rate** (optional): If provided, must match the supported configurations listed above. If omitted, automatically determined from width and height. -While the API accepts width and height values within the min/max ranges, only the specific resolution and refresh rate combinations listed in the supported configurations table are actually supported. The server will reject any unsupported combinations. +While the API accepts width and height values within the min/max ranges, only the specific resolution and refresh rate combinations listed in the supported configurations table are actually supported. When refresh_rate is omitted, it will be automatically determined if the width and height match a supported configuration exactly. The server will reject any unsupported combinations. ## Considerations From e2c562c163e66f2655669e497dacebe0616443b6 Mon Sep 17 00:00:00 2001 From: Hiro Tamada Date: Mon, 13 Oct 2025 11:16:04 -0400 Subject: [PATCH 3/9] moar --- browsers/viewport.mdx | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/browsers/viewport.mdx b/browsers/viewport.mdx index 6959019..f398e9b 100644 --- a/browsers/viewport.mdx +++ b/browsers/viewport.mdx @@ -183,14 +183,20 @@ default_viewport = await client.browsers.create() ## Viewport constraints -The viewport configuration has the following constraints: -- **Width** (required): Minimum 320px, Maximum 7680px -- **Height** (required): Minimum 240px, Maximum 4320px -- **Refresh Rate** (optional): If provided, must match the supported configurations listed above. If omitted, automatically determined from width and height. - - -While the API accepts width and height values within the min/max ranges, only the specific resolution and refresh rate combinations listed in the supported configurations table are actually supported. When refresh_rate is omitted, it will be automatically determined if the width and height match a supported configuration exactly. The server will reject any unsupported combinations. - +Only the specific viewport configurations listed in the [supported configurations table](#supported-viewport-configurations) above are supported: +- **2560x1440** (QHD) at 10 Hz +- **1920x1080** (Full HD) at 25 Hz +- **1920x1200** (WUXGA) at 25 Hz +- **1440x900** (WXGA+) at 25 Hz +- **1024x768** (XGA) at 60 Hz + +When specifying a viewport: +- **Width** and **Height** are required and must match one of the supported configurations exactly +- **Refresh Rate** is optional - if omitted, it will be automatically determined from the width and height combination + + +The server will reject any viewport configuration that doesn't exactly match one of the supported combinations listed above. + ## Considerations From bc3720cf100a1be55806a4b82e5b36869313209b Mon Sep 17 00:00:00 2001 From: Hiro Tamada Date: Mon, 13 Oct 2025 11:21:53 -0400 Subject: [PATCH 4/9] moar --- browsers/viewport.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browsers/viewport.mdx b/browsers/viewport.mdx index f398e9b..8c079b4 100644 --- a/browsers/viewport.mdx +++ b/browsers/viewport.mdx @@ -1,5 +1,5 @@ --- -title: "Viewport Configuration" +title: "Viewport" description: "Configure browser viewport size and refresh rate for your automations" --- From 31a9c80192c08c1b4863fc0a6400a3a83e66000e Mon Sep 17 00:00:00 2001 From: Hiro Tamada Date: Mon, 13 Oct 2025 11:30:47 -0400 Subject: [PATCH 5/9] moar --- browsers/viewport.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browsers/viewport.mdx b/browsers/viewport.mdx index 8c079b4..88d8765 100644 --- a/browsers/viewport.mdx +++ b/browsers/viewport.mdx @@ -1,5 +1,5 @@ --- -title: "Viewport" +title: "Viewports" description: "Configure browser viewport size and refresh rate for your automations" --- From f782e2faf380eeed56dc067b41e6bfa2dee870c8 Mon Sep 17 00:00:00 2001 From: Hiro Tamada Date: Mon, 13 Oct 2025 13:32:19 -0400 Subject: [PATCH 6/9] moar --- info/pricing.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/info/pricing.mdx b/info/pricing.mdx index 9bf2f83..4383ac2 100644 --- a/info/pricing.mdx +++ b/info/pricing.mdx @@ -16,6 +16,7 @@ With Kernel, you only pay for what you use and nothing more. Our goal is to be c | Browser live view & logs | ✅ | ✅ | ✅ | | Browser replays | ❌ | ✅ | ✅ | | Browser profiles | ❌ | ✅ | ✅ | +| Browser viewports | ✅ | ✅ | ✅ | | File uploads & downloads | ❌ | ✅ | ✅ | | Configurable browser extensions | ❌ | Coming soon | Coming soon | | BYO images & storage mounts | ❌ | ❌ | Coming soon | From 7d09d4edd3fee4b9522d8f71b526e2a00cbad965 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 13 Oct 2025 17:32:29 +0000 Subject: [PATCH 7/9] docs: update code samples from OpenAPI --- snippets/openapi/post-browsers-id-extensions.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/snippets/openapi/post-browsers-id-extensions.mdx b/snippets/openapi/post-browsers-id-extensions.mdx index 91b4802..8c11441 100644 --- a/snippets/openapi/post-browsers-id-extensions.mdx +++ b/snippets/openapi/post-browsers-id-extensions.mdx @@ -6,7 +6,7 @@ const client = new Kernel({ apiKey: 'My API Key', }); -await client.browsers.uploadExtensions('id', { +await client.browsers.loadExtensions('id', { extensions: [{ name: 'name', zip_file: fs.createReadStream('path/to/file') }], }); ``` @@ -18,7 +18,7 @@ from kernel import Kernel client = Kernel( api_key="My API Key", ) -client.browsers.upload_extensions( +client.browsers.load_extensions( id="id", extensions=[{ "name": "name", From d3d32fd26ccffeafd8eecfe4e7bfdd9d5737e4fd Mon Sep 17 00:00:00 2001 From: Daniel Prevoznik Date: Mon, 13 Oct 2025 14:16:22 -0400 Subject: [PATCH 8/9] Update browser-use.mdx Added informational note about Browser Use's configuration options. --- integrations/browser-use.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/integrations/browser-use.mdx b/integrations/browser-use.mdx index 95ee913..232f258 100644 --- a/integrations/browser-use.mdx +++ b/integrations/browser-use.mdx @@ -38,12 +38,16 @@ Replace your existing Browser initialization to use Kernel's CDP URL and display browser = Browser( cdp_url=kernel_browser.cdp_ws_url, headless=False, - window_size={'width': 1024, 'height': 786}, - viewport={'width': 1024, 'height': 786}, + window_size={'width': 1024, 'height': 768}, + viewport={'width': 1024, 'height': 768}, device_scale_factor=1.0 ) ``` + +Browser Use supports a wide range of browser configuration parameters. See the full list in the Browser Use docs. When running on Kernel, remember that browsers must use one of Kernel’s supported viewport sizes and refresh rates—see Viewports for the supported configurations. + + ### 4. Create and run your agent Use your existing Agent setup with the Kernel-powered browser: From ece821b5bdc7db08bd75aa058a84d43a3b0911e3 Mon Sep 17 00:00:00 2001 From: Hiro Tamada Date: Mon, 13 Oct 2025 14:49:17 -0400 Subject: [PATCH 9/9] moar --- info/pricing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/info/pricing.mdx b/info/pricing.mdx index 4383ac2..5295907 100644 --- a/info/pricing.mdx +++ b/info/pricing.mdx @@ -14,9 +14,9 @@ With Kernel, you only pay for what you use and nothing more. Our goal is to be c | Free usage credits / mo | $5 | $50 | Custom | | Browser persistence | ✅ | ✅ | ✅ | | Browser live view & logs | ✅ | ✅ | ✅ | +| Browser viewports | ✅ | ✅ | ✅ | | Browser replays | ❌ | ✅ | ✅ | | Browser profiles | ❌ | ✅ | ✅ | -| Browser viewports | ✅ | ✅ | ✅ | | File uploads & downloads | ❌ | ✅ | ✅ | | Configurable browser extensions | ❌ | Coming soon | Coming soon | | BYO images & storage mounts | ❌ | ❌ | Coming soon |