Save and Reuse Profile State

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.

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

from kernel import Kernel, ConflictError

kernel = Kernel()

try:
    await kernel.profiles.create(name="checkout-session")
except ConflictError:
    pass

package main

import (
	"context"
	"errors"
	"net/http"

	"github.com/kernel/kernel-go-sdk"
)

func main() {
	ctx := context.Background()
	client := kernel.NewClient()

	_, err := client.Profiles.New(ctx, kernel.ProfileNewParams{
		Name: kernel.String("checkout-session"),
	})
	if err != nil {
		var apiErr *kernel.Error
		if errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusConflict {
			return
		}
		panic(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.

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

browser = await kernel.browsers.create(
    profile={
        "name": "checkout-session",
        "save_changes": True,
    }
)

browser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
	Profile: shared.BrowserProfileParam{
		Name:        kernel.String("checkout-session"),
		SaveChanges: kernel.Bool(true),
	},
})
if err != nil {
	panic(err)
}

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.

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

print("Live view:", browser.browser_live_view_url)

# Navigate and create the state you want to preserve.

await kernel.browsers.delete_by_id(browser.session_id)

fmt.Println("Live view:", browser.BrowserLiveViewURL)

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

if err := client.Browsers.DeleteByID(ctx, browser.SessionID); err != nil {
	panic(err)
}

4. Load the saved state

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

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

next_browser = await kernel.browsers.create(
    profile={"name": "checkout-session"}
)

nextBrowser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
	Profile: shared.BrowserProfileParam{
		Name: kernel.String("checkout-session"),
	},
})
if err != nil {
	panic(err)
}

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.

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

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

browser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{
	Profile: shared.BrowserProfileParam{
		Name: kernel.String("checkout-session"),
	},
	StartURL: kernel.String("https://example.com/dashboard"),
})
if err != nil {
	panic(err)
}

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.

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

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

browser = await kernel.browsers.create()

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

browser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{})
if err != nil {
	panic(err)
}

_, err = client.Browsers.Update(ctx, browser.SessionID, kernel.BrowserUpdateParams{
	Profile: shared.BrowserProfileParam{
		Name: kernel.String("checkout-session"),
	},
})
if err != nil {
	panic(err)
}

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

Loading a profile this way restores all of its saved tabs, which can leave the browser with several tabs open at once. Pass start_url in the same update() call to collapse those restored tabs down to a single tab at the page you specify.

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

await kernel.browsers.update(
    browser.session_id,
    profile={"name": "checkout-session"},
    start_url="https://example.com/dashboard",
)

_, err = client.Browsers.Update(ctx, browser.SessionID, kernel.BrowserUpdateParams{
	Profile: shared.BrowserProfileParam{
		Name: kernel.String("checkout-session"),
	},
	StartURL: kernel.String("https://example.com/dashboard"),
})
if err != nil {
	panic(err)
}

Rename and manage profiles

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

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

await kernel.profiles.update(
    "checkout-session",
    name="checkout-session-v2",
)

_, err := client.Profiles.Update(ctx, "checkout-session", kernel.ProfileUpdateParams{
	Name: "checkout-session-v2",
})

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

Overview

Working with your browser

Integrations

Migrations

deploying your agent

Agent Skills

Community

Info

Save and Reuse Profile State

1. Create a profile

2. Start a writer browser

3. Use and delete the browser

4. Load the saved state

Control the starting tab

Load a profile after browser creation

Rename and manage profiles

​1. Create a profile

​2. Start a writer browser

​3. Use and delete the browser

​4. Load the saved state

​Control the starting tab

​Load a profile after browser creation

​Rename and manage profiles

1. Create a profile

2. Start a writer browser

3. Use and delete the browser

4. Load the saved state

Control the starting tab

Load a profile after browser creation

Rename and manage profiles