Appearance
Fresh 🌱
Overview
Pre-configure pools of reserved browsers for immediate acquisition
Browser pools let you maintain a set of reserved, identical browsers ready for immediate use. Use them to set your preferred browser configuration in advance, allowing you to minimize browser start-up latency and scale your workloads in production.
How browser pools work
Browser pools are a way to pre-configure a fixed set of browsers without being charged for them until they are used (i.e. acquired). All browsers in the pool share the same settings upon instantiation.
Declare a pool
First, declare a pool of browsers with your specified configuration. The pool takes time to fill (see fill rate per minute), so declare your pool outside your browser automation / agent runtime logic.
INFO
Pool declarations should be decoupled from browser runtime logic for the best performance.
Acquire a browser
You can acquire a browser as soon as you've created a pool. The request returns immediately if a browser is available, or waits until one becomes available.
The total number of browsers is fixed to the `size` specified upon browser pool creation. When you acquire a browser, the pool's available count is decremented by one. When you release a browser, the pool's available count is incremented by one.
INFO
Put differently, the pool does not top up when you acquire a browser: browsers are "borrowed" from the pool and must be returned when you're done with them, either by releasing them or allowing them to timeout.
Release a browser
When you're done with a browser, release it back to the pool. this step is important; otherwise, the browser will continue to be in an `acquired` state until it times out.
INFO
Failing to release browsers may result in unexpected latency when acquiring future browsers.
Create a pool of reserved browsers
Create a browser pool with a specified size and configuration. All browsers in the pool share the same settings.
typescript
import Kernel from '@onkernel/sdk';
const kernel = new Kernel();
const pool = await kernel.browserPools.create({
name: "my-pool",
size: 10,
stealth: true,
headless: false,
timeout_seconds: 600,
start_url: "https://example.com",
viewport: {
width: 1280,
height: 800
}
});
console.log(pool.id);python
from kernel import Kernel
kernel = Kernel()
pool = kernel.browser_pools.create(
name="my-pool",
size=10,
stealth=True,
headless=False,
timeout_seconds=600,
start_url="https://example.com",
viewport={
"width": 1280,
"height": 800
}
)
print(pool.id)Pool configuration options
Pools can be pre-configured with options like start url, custom extensions, supported viewports, residential proxies, profiles, and more. See the API reference for more details.
Acquire a browser
Acquire a browser from the pool. The request returns immediately if a browser is available, or waits until one becomes available. The acquire_timeout_seconds parameter controls how long to wait; it defaults to the calculated time it would take to fill the pool at the pool's configured fill rate.
typescript
const browser = await kernel.browserPools.acquire("my-pool", {
acquire_timeout_seconds: 30,
});
console.log(browser.session_id);
console.log(browser.cdp_ws_url);python
browser = kernel.browser_pools.acquire(
"my-pool",
acquire_timeout_seconds=30,
)
print(browser.session_id)
print(browser.cdp_ws_url)The acquired browser includes all the same properties as a regular browser session, including cdp_ws_url for CDP connections and browser_live_view_url for live viewing.
Timeout behavior
Browsers remain in the pool indefinitely until acquired. Once acquired, the pool's timeout_seconds applies just like a regular browser timeout, if the browser is idle (no CDP or live view connection) for longer than the timeout, it is destroyed and not returned to the pool. The pool will automatically create a replacement browser at the pool's configured fill rate.
Release a browser
When you're done with a browser, release it back to the pool. By default, the browser instance is reused. Set reuse: false to destroy it and create a fresh one.
typescript
await kernel.browserPools.release("my-pool", {
session_id: browser.session_id,
reuse: true,
});python
kernel.browser_pools.release(
"my-pool",
session_id=browser.session_id,
reuse=True,
)Update a pool
Update the pool configuration. By default, all idle browsers are discarded and rebuilt with the new configuration.
typescript
const updatedPool = await kernel.browserPools.update("my-pool", {
size: 20,
stealth: true,
});python
updated_pool = kernel.browser_pools.update(
"my-pool",
size=20,
stealth=True,
)INFO
The size parameter is always required when updating a pool, even if you only want to change other settings.
By default, updating a pool discards all idle browsers and rebuilds them with the new configuration. Set discard_all_idle: false to keep existing idle browsers and only apply the new configuration to newly created browsers.
Flush idle browsers
Destroy all idle browsers in the pool. Acquired browsers are not affected. The pool will automatically refill with the pool's specified configuration.
typescript
await kernel.browserPools.flush("my-pool");python
kernel.browser_pools.flush("my-pool")Get pool details
Retrieve the current status and configuration of a pool.
typescript
const pool = await kernel.browserPools.retrieve("my-pool");
console.log(pool.available_count);
console.log(pool.acquired_count);python
pool = kernel.browser_pools.retrieve("my-pool")
print(pool.available_count)
print(pool.acquired_count)List pools
List all browser pools in your organization.
typescript
const pools = await kernel.browserPools.list();
for (const pool of pools) {
console.log(pool.name, pool.available_count);
}python
pools = kernel.browser_pools.list()
for pool in pools:
print(pool.name, pool.available_count)Delete a pool
Delete a browser pool and all browsers in it. By default, deletion is blocked if browsers are currently acquired. Use force: true to terminate acquired browsers and force deletion.
typescript
// Delete a pool (fails if browsers are acquired)
await kernel.browserPools.delete("my-pool");
// Force delete even if browsers are acquired
await kernel.browserPools.delete("my-pool", { force: true });python
# Delete a pool (fails if browsers are acquired)
kernel.browser_pools.delete("my-pool")
# Force delete even if browsers are acquired
kernel.browser_pools.delete("my-pool", force=True)Full example
This example assumes you've already created a pool named "my-pool". In practice, you'd create pools once (via the SDK, CLI, or dashboard) and then acquire from them repeatedly.
typescript
import Kernel from '@onkernel/sdk';
import { chromium } from 'playwright';
const kernel = new Kernel();
// Acquire a browser from an existing pool
const kernelBrowser = await kernel.browserPools.acquire("my-pool", {});
try {
// Connect via CDP
const browser = await chromium.connectOverCDP(kernelBrowser.cdp_ws_url);
const context = browser.contexts()[0];
const page = context.pages()[0];
await page.goto('https://example.com');
const title = await page.title();
console.log(title);
} finally {
// Release back to pool for reuse
await kernel.browserPools.release("my-pool", {
session_id: kernelBrowser.session_id,
});
}python
import asyncio
from kernel import Kernel
from playwright.async_api import async_playwright
kernel = Kernel()
async def main():
# Acquire a browser from an existing pool
kernel_browser = kernel.browser_pools.acquire("my-pool")
async with async_playwright() as playwright:
try:
# Connect via CDP
browser = await playwright.chromium.connect_over_cdp(kernel_browser.cdp_ws_url)
context = browser.contexts[0]
page = context.pages[0]
await page.goto('https://example.com')
title = await page.title()
print(title)
finally:
# Release back to pool for reuse
kernel.browser_pools.release(
"my-pool",
session_id=kernel_browser.session_id,
)
asyncio.run(main())API reference
For more details on all available endpoints and parameters, see the Browser Pools API reference.