Overview

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 (such as stealth, proxies, extensions, and profiles), allowing you to minimize browser start-up latency and scale your workloads in production.

Acquiring a browser from a pool is faster than creating a browser directly. Reserved browsers and on-demand browsers share the same concurrency limit, and reserved browsers aren't billed until they're used. See Scale for how pools fit into best practices for production architecture.

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.

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.

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);

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.

A profile attached to a pool is loaded read-only: pooled browsers never persist changes back to the profile, so save_changes does not apply to pools (it is silently ignored if sent). To capture profile state, use a single browser session with save_changes instead — see Profiles.

When a pool has a profile attached, refresh_on_profile_update is automatically enabled — the pool flushes idle browsers whenever the profile's contents are updated, so it always picks up the latest profile data. See Refresh on profile update below.

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.

const browser = await kernel.browserPools.acquire("my-pool", {
  acquire_timeout_seconds: 30,
});

console.log(browser.session_id);
console.log(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.

await kernel.browserPools.release("my-pool", {
  session_id: browser.session_id,
  reuse: true,
});

Update a pool

Update the pool configuration. By default, existing idle browsers keep their current configuration and only newly created browsers use the new one. Pass discard_all_idle: true to discard all idle browsers and rebuild them immediately with the new configuration.

const updatedPool = await kernel.browserPools.update("my-pool", {
  size: 20,
  stealth: true,
});

By default (discard_all_idle: false), updating a pool leaves existing idle browsers untouched — they keep their original configuration, and only browsers created after the update use the new configuration. Set discard_all_idle: true to discard all idle browsers and rebuild them immediately with the new configuration.

Refresh on profile update

When a pool is configured with a profile, the profile data is loaded into each browser when it's created. Normally, updating the profile's contents (for example, re-saving cookies or auth state to the same profile) does not propagate to already-warmed browsers — only newly-filled browsers use the updated profile.

refresh_on_profile_update is automatically set to true when a pool is created with a profile, or when an existing pool's profile is changed. This ensures that acquired browsers always get the latest profile data without manual intervention. You can explicitly set it to false to opt out.

When a pool's profile is removed (by passing { "id": "" }), refresh_on_profile_update is forced to false.

How it works

When a profile is saved (for example, after a successful Managed Auth login or a save_changes browser session), Kernel checks whether any browser pools use that profile with refresh_on_profile_update enabled. If so, all idle browsers in each matching pool are flushed — they are replaced with fresh browsers that load the updated profile. Acquired browsers are not affected; they continue running with the profile data they were created with.

Per-user profiles with pools

A profile attached to the pool config is read-only and shared by every browser, so it can't hold per-user login state across many users in a single pool. To use a pool's pre-warmed browsers to load many different per-user profiles and persist each user's state, attach the profile to the browser after you acquire it, then destroy the browser on release:

1. Create the pool with no profile. A profile can only be loaded into a browser that was created without one, so the pool must be profile-free.
2. Acquire a browser from the pool.
3. Attach the user's profile with save_changes: true using kernel.browsers.update().
4. Run your automation, then release with reuse: false. This destroys the browser instead of returning it to the pool — which both persists the profile changes and prevents state from leaking to the next user.

// Declare the pool once, separately from your workload runtime, with no profile attached
const pool = await kernel.browserPools.create({ name: "my-pool", size: 10 });

// Later, at runtime, acquire from the pool per user:
const browser = await kernel.browserPools.acquire("my-pool", {});

// Load this user's profile and persist any changes on destroy
await kernel.browsers.update(browser.session_id, {
  profile: { name: userId, save_changes: true },
});

// ... run your automation against browser.cdp_ws_url ...

// Destroy on release so the profile persists and no state leaks to the next user
await kernel.browserPools.release("my-pool", {
  session_id: browser.session_id,
  reuse: false,
});

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.

await kernel.browserPools.flush("my-pool");

Get pool details

Retrieve the current status and configuration of a pool.

const pool = await kernel.browserPools.retrieve("my-pool");

console.log(pool.available_count);
console.log(pool.acquired_count);

List pools

List all browser pools in your organization.

const pools = await kernel.browserPools.list();

for (const pool of pools) {
  console.log(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.

// 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 });

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.

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,
  });
}

API reference

For more details on all available endpoints and parameters, see the Browser Pools API reference.