Browser Profiles

Persist browser state across sessions

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

Profiles let you save and reuse browser state (cookies, local storage, and session storage) across multiple sessions. This is useful for maintaining login states, preserving user preferences, or building realistic multi-session workflows.

How Profiles Work

A profile is a saved snapshot of a browser’s cookies, local storage, and session storage. Other browser data, such as the HTTP cache, history, and extensions, is not saved. By default, each Notte session uses a fresh browser state to ensure isolation.

When you create a profile and use it in a session with persist=True, Notte saves that session’s browser state when the session ends. You can also save any running session into a profile at any time with save_profile(). You can then attach the profile to future sessions to restore the saved state.

Create a Profile

Create a profile to store browser state. Optionally, give it a name to keep track of different profiles:

create_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Create a profile with optional name
profile = client.profiles.create(name="my-profile")

print(f"Profile created: {profile.profile_id}")
print(f"Profile name: {profile.name}")

Use a Profile in a Session

Attach a profile to a session to load saved browser state:

use_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Use an existing profile in a session
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
    # Session loads saved browser state from the profile
    session.execute(type="goto", url="https://example.com")

Persist Changes

The persist parameter controls whether session changes are saved back to the profile:

• True - Save browser state to the profile when the session ends
• False (default) - Use the profile as read-only; don’t save changes

Set persist=True the first time you use a new profile to save the initial browser state. After that, you can use persist=False to reuse the profile without modifying it.

Profile Login Example

Step 1: Login and Save to Profile

First, create a profile and perform a login. When the session ends with persist=True, all cookies and browser state are saved to the profile:

persist_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Create a new profile
profile = client.profiles.create(name="github-login")

# Use profile with persist=True to save browser state
with client.Session(profile={"id": profile.profile_id, "persist": True}) as session:
    # Navigate and perform login
    session.execute(type="goto", url="https://github.com/login")
    session.execute(type="fill", selector='input[name="login"]', value="username")
    session.execute(type="fill", selector='input[name="password"]', value="password")
    session.execute(type="click", selector='input[type="submit"]')
    # Browser state is saved to profile when session ends

Save a Running Session

If you only decide to keep the browser state after the session has started, save it directly. save_profile() snapshots the running session into a new profile (name) or an existing one (profile_id) and the session keeps running. It works on any session, including one started without a profile or with persist=False. With neither argument, it saves into the profile the session was started with.

save_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Start a session without a profile, or with a read-only one
with client.Session() as session:
    session.execute(type="goto", url="https://example.com")
    # ... log in ...

    # Save the current browser state into a new profile; the session keeps running
    profile = session.save_profile(name="example-login")
    print(profile.profile_id, profile.persisted_domains)

    # Later saves can overwrite the same profile
    again = session.save_profile(profile_id=profile.profile_id)

results = [profile.name, again.profile_id == profile.profile_id]

save_profile() does not change the session’s persist setting. A session started with persist=True still saves again when it ends.

Step 2: Reuse the Saved Profile

Use the saved profile in a new session. The browser automatically loads the saved state, so you’re already authenticated:

reuse_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Reuse a previously saved profile (read-only)
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
    # Navigate directly - already authenticated!
    session.execute(type="goto", url="https://github.com")

    # Perform actions as logged-in user
    obs = session.observe()
    print(f"Page title: {obs.metadata.title}")

What happens:

1. A new session is created using the same profile ID
2. The browser loads saved cookies and state from the profile
3. You navigate directly without needing to log in again
4. The session picks up right where the previous one left off

This pattern is useful for:

• Avoiding repeated logins across automation runs
• Testing authenticated user flows
• Managing multiple accounts with separate profiles
• Maintaining session state over time

Using Profiles with Agents

Profiles work seamlessly with Notte Agents. An agent running with a pre-authenticated profile can access authenticated resources immediately:

profile_with_agent.py

from notte_sdk import NotteClient

client = NotteClient()

# Use a profile with an agent
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
    agent = client.Agent(session=session, max_steps=10)

    # Agent runs with pre-authenticated session
    response = agent.run(
        task="Go to my GitHub notifications and summarize them", url="https://github.com/notifications"
    )

    print(f"Agent response: {response.answer}")

Managing Profiles

List Profiles

Retrieve all your profiles with optional filtering:

list_profiles.py

from notte_sdk import NotteClient

client = NotteClient()

# List all profiles
profiles = client.profiles.list()

for profile in profiles:
    print(f"- {profile.name}: {profile.profile_id}")

# Filter by name
filtered = client.profiles.list(name="github")
print(f"Found {len(filtered)} profiles matching 'github'")

Get Profile Details

Retrieve information about a specific profile:

get_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Get profile details
profile = client.profiles.get("notte-profile-abc123")

print(f"Profile ID: {profile.profile_id}")
print(f"Profile Name: {profile.name}")
print(f"Created At: {profile.created_at}")

Delete a Profile

Delete a profile when you no longer need it:

delete_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Delete a profile
deleted = client.profiles.delete("notte-profile-abc123")

if deleted:
    print("Profile deleted successfully")

Read-Only Profile Usage

Load a profile without saving changes by setting persist=False:

use_profile.py

from notte_sdk import NotteClient

client = NotteClient()

# Use an existing profile in a session
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
    # Session loads saved browser state from the profile
    session.execute(type="goto", url="https://example.com")

Use cases for read-only profiles:

• Test workflows without affecting saved state
• Run parallel sessions with the same profile safely
• Maintain a clean baseline profile for repeated use

By default, persist is False, so you don’t have to explicitly specify it for read-only access.

Best Practices

Profile Management

• Use descriptive names to identify profiles by their purpose (e.g., github-login, twitter-bot-1)
• Create separate profiles for different accounts or services
• Periodically verify that saved sessions are still valid

Security

• Profiles contain sensitive session data; treat profile IDs as secrets
• Delete profiles for accounts that are no longer needed
• Use separate profiles for production and development environments

Comparison: Profiles vs Cookies

Feature	Profiles	Cookies
Scope	Cookies, local storage, and session storage	Cookies only
Storage	Managed by Notte	JSON file you manage
Persistence	Automatic on session end	Manual export/import
Use case	Long-term state preservation	Quick cookie injection

Use profiles when you need to preserve cookies and web storage together. Use cookies when you only need to inject specific authentication tokens.

Next Steps

Session Lifecycle

Manage session lifecycle

Cookies

Manual cookie management

Vaults

Secure credential storage

Session Configuration

All session options