| title | Overview |
|---|---|
| description | 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.
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.
The total number of usable 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. 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](#release-a-browser) or allowing them to [timeout](#timeout-behavior).
Create a browser pool with a specified size and configuration. All browsers in the pool share the same settings.
```typescript Typescript/Javascript 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, viewport: { width: 1280, height: 800 } });
console.log(pool.id);
```python Python
from kernel import Kernel
kernel = Kernel()
pool = kernel.browser_pools.create(
name="my-pool",
size=10,
stealth=True,
headless=False,
timeout_seconds=600,
viewport={
"width": 1280,
"height": 800
}
)
print(pool.id)
Pools can be pre-configured with options like custom extensions, supported viewports, residential proxies, profiles, and more. See the API reference for more details.
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.
console.log(browser.session_id); console.log(browser.cdp_ws_url);
```python 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.
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.
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.
kernel.browser_pools.release(
"my-pool",
session_id=browser.session_id,
reuse=True,
)Update the pool configuration. By default, all idle browsers are discarded and rebuilt with the new configuration.
```typescript Typescript/Javascript const updatedPool = await kernel.browserPools.update("my-pool", { size: 20, stealth: true, }); ```updated_pool = kernel.browser_pools.update(
"my-pool",
size=20,
stealth=True,
)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.
Destroy all idle browsers in the pool. Acquired browsers are not affected. The pool will automatically refill with the pool's specified configuration.
```typescript Typescript/Javascript await kernel.browserPools.flush("my-pool"); ```kernel.browser_pools.flush("my-pool")Retrieve the current status and configuration of a pool.
```typescript Typescript/Javascript const pool = await kernel.browserPools.retrieve("my-pool");console.log(pool.available_count); console.log(pool.acquired_count);
```python Python
pool = kernel.browser_pools.retrieve("my-pool")
print(pool.available_count)
print(pool.acquired_count)
List all browser pools in your organization.
```typescript Typescript/Javascript const pools = await kernel.browserPools.list();for (const pool of pools) { console.log(pool.name, pool.available_count); }
```python Python
pools = kernel.browser_pools.list()
for pool in pools:
print(pool.name, pool.available_count)
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.
// Force delete even if browsers are acquired await kernel.browserPools.delete("my-pool", { force: true });
```python 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)
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 Typescript/Javascript 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 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())
For more details on all available endpoints and parameters, see the Browser Pools API reference.