Save and Reuse Profile State

Create a browser profile, save state to it, and load it in later browser sessions

This guide creates a profile, writes browser state to it, and reuses the saved state in a later browser session.

1. Create a profile

Give the profile a meaningful name that is unique within your project.

TypeScript

import Kernel, { ConflictError } from '@onkernel/sdk';

const kernel = new Kernel();

try {
  await kernel.profiles.create({ name: 'checkout-session' });
} catch (err) {
  if (!(err instanceof ConflictError)) {
    throw err;
  }
}

2. Start a writer browser

Attach the profile by name or id. Set save_changes to true only when this browser owns writes to the profile.

TypeScript

const browser = await kernel.browsers.create({
  profile: {
    name: 'checkout-session',
    save_changes: true,
  },
});

Before starting more than one writer, read Sharing and concurrency. Profile saves replace the complete stored snapshot and don’t merge concurrent changes.

3. Use and delete the browser

Navigate, authenticate, or complete the part of the workflow whose state you want to retain. Then delete the Kernel browser to save the state.

Calling browser.close() only closes the Playwright connection. It doesn’t save the profile. You must delete the Kernel browser or let it time out.

TypeScript

console.log('Live view:', browser.browser_live_view_url);

// Navigate and create the state you want to preserve.

await kernel.browsers.deleteByID(browser.session_id);

4. Load the saved state

Create another browser with the same profile. Omit save_changes to keep the stored profile unchanged during this run.

TypeScript

const nextBrowser = await kernel.browsers.create({
  profile: { name: 'checkout-session' },
});

Control the starting tab

By default, a profile restores its saved tabs. Pass start_url to discard those restored tabs and open a specific page when the browser starts.

TypeScript

const browser = await kernel.browsers.create({
  profile: { name: 'checkout-session' },
  start_url: 'https://example.com/dashboard',
});

The same behavior applies to browser pools configured with both a profile and a start URL.

Managed Auth controls the tab state of profiles attached to auth connections. Each login or automatic reauthentication starts with one tab at the configured login URL, or at the domain homepage when no login URL is configured. Successful authentication saves the resulting tab state. Failed and canceled sessions leave the profile unchanged.

Set start_url when you create a browser if your automation requires a specific first page.

Load a profile after browser creation

You can attach a profile to a running browser that was created without one. Loading the profile restarts Chromium, so reconnect your CDP or Playwright client afterward.

TypeScript

const browser = await kernel.browsers.create();

await kernel.browsers.update(browser.session_id, {
  profile: { name: 'checkout-session' },
});

You can’t load a profile into a browser that already has one. The browser must have been created without a profile configuration.

Rename and manage profiles

Renaming a profile doesn’t recreate or change its stored state. The new name must be unique within the project.

TypeScript

await kernel.profiles.update('checkout-session', {
  name: 'checkout-session-v2',
});

Use the Profiles API reference or CLI reference to list, inspect, download, rename, and delete profiles.