overview.mdx

title	Overview
description	Persist and reuse browser session state (cookies, local storage) across sessions

Profiles let you capture browser state created during a session (cookies and local storage) and reuse it in later sessions. This is useful for persisting login state, site preferences, and starting on the same page across browser sessions.

If you're looking to maintain authenticated browser sessions, check out [Managed Auth](/profiles/managed-auth/overview).

1. Create a profile

The first step in using profiles is to create one, optionally giving it a meaningful name that is unique within your organization.

```typescript Typescript/Javascript import Kernel, { ConflictError } from '@onkernel/sdk';

const kernel = new Kernel();

try { await kernel.profiles.create({ name: 'profiles-demo' }); } catch (err) { if (err instanceof ConflictError) { // Profile already exists } else { throw err; } }

```python Python
from kernel import Kernel, ConflictError

kernel = Kernel()

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

2. Start a browser session using the profile and save changes

After creating the profile, reference it by its name or id when creating a browser. Set save_changes to true to persist any state created during this session back into the profile when the browser is closed.

```typescript Typescript/Javascript const kernelBrowser = await kernel.browsers.create({ profile: { name: 'profiles-demo', save_changes: true, }, }); ```

kernel_browser = await kernel.browsers.create(
    profile={
        "name": "profiles-demo",
        "save_changes": True,
    }
)

3. Use the browser, then close it to persist the state

After using a browser with save_changes: true, closing the browser will save cookies and local storage into the profile.

Calling `browser.close()` does **not** save the profile state. You **must** explicitly delete the Kernel browser (or let the browser [timeout](/browsers/termination#automatic-deletion-via-timeout)) to persist the Profile. ```typescript Typescript/Javascript console.log('Live view:', kernelBrowser.browser_live_view_url);

// Navigate and create login state...

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

```python Python
print("Live view:", kernel_browser.browser_live_view_url)

# Navigate and create login state...

await kernel.browsers.delete_by_id(kernel_browser.session_id)

4. Start a new session with the saved profile (read-only)

Create another browser using the same profile name. Omitting save_changes leaves the stored profile untouched.

```typescript Typescript/Javascript const kernelBrowser2 = await kernel.browsers.create({ profile: { name: 'profiles-demo' }, });

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

```python Python
kernel_browser2 = await kernel.browsers.create(
    profile={"name": "profiles-demo"}
)
print("Live view:", kernel_browser2.browser_live_view_url)

Loading a profile into an existing browser

You can load a profile into a browser after it has been created using the update browser endpoint.

```typescript Typescript/Javascript // Create a browser without a profile const kernelBrowser = await kernel.browsers.create();

// Later, load a profile into the browser await kernel.browsers.update(kernelBrowser.session_id, { profile: { name: 'profiles-demo' } });

```python Python
# Create a browser without a profile
kernel_browser = await kernel.browsers.create()

# Later, load a profile into the browser
await kernel.browsers.update(kernel_browser.session_id, profile={"name": "profiles-demo"})

You cannot load a profile into a browser that was already created with a profile. The browser must have been created without any profile configuration.

Other ways to use profiles

The API and SDKs support listing, deleting, and downloading profile data as JSON. See the API reference for more details.

Notes

• A profile's name must be unique within your organization.
• Profiles store cookies and local storage. Start the session with save_changes: true to write changes back when the browser is closed.
• To keep a profile immutable for a run, omit save_changes (default) when creating the browser.
• Multiple browsers in parallel can use the same profile, but only one browser should write (save_changes: true) to it at a time. Parallel browsers with save_changes: true may cause profile corruption and unpredictable behavior.
• Profile data is encrypted end to end using a per-organization key.
• Browsers loaded with a profile start on the same page as the page last visited using that profile.