Persistent Sessions & Profiles

Learn about Persistent (sticky) Sessions and Persistent Profiles on Oxylabs Agent Browser. Reconnect to ongoing sessions and reuse your cookies or local storage though multiple sessions.

Managing long-running multi-stage automation workflows or maintaining logged-in user states across distinct connection sequences requires persisting browser states. Oxylabs Agent Browser offers two advanced persistence systems:

Persistent Sessions	Keep a live remote browser environment running across client disconnections.
Persistent Profiles	Save and restore cookies, local storage, and browser cache.

Persistent Sessions

Persistent (sticky) Sessions keep your remote browser instance running in the cloud (even when your local automation script disconnects) by defining a custom session_name to your connection URL:

wss://USER:[e-mail]?session_name=checkout-flow-test

Persistent Sessions are enabled by default for all users, with a default limit of 5 concurrent sessions. If you need a higher limit, contact Oxylabs support (live chat or email) or your Dedicated Account Manager.

Parameter	Description	Type
session_name	When defined, a sessions persist up to the maximum time-to-live (TTL) (max 24h or until stopped). Reconnect with the same session_name to reattach the same session ID and existing tabs. Supported format: ^[A-Za-z0-9-]{3,36}$	String
keep_alive	While false (default), calling browser.close() reclaims and closes the session. While true, the session stays on in the cloud after you disconnect (up to 10 minutes).	Boolean

Reconnect to an existing tab

// Reconnect to existing session with 
const browser = await chromium.connectOverCDP(endpoint);
const ctx = browser.contexts()[0];
const page = ctx.pages().find(p => p.url().includes("http://example.com "));

Persistent Profiles

Persistent Profiles are enabled by default for all users, with a default limit of 5 profiles. Use it to save cookies and localStorage under a named profile and restore them in a brand-new session. The following parameters allow you to maintain a logged-in persona across sessions without re-authenticating every time:

Parameter	Description	Type
o_profile	Save/restore cookies and localStorage with a named profile (14 days from last use). Supported format: ^[A-Za-z0-9_-]{1,36}$	String
o_profile_save	Force profile save during or at the end of the seesion. Default: false.	Boolean
proxy_resi_ses_id	Custom session ID to pin residential exit IP across sessions. Supported format: ^[A-Za-z0-9]{3,36}$.	String
proxy_resi_ses_time	Duration to hold the pinned residential proxy exit IP in minutes. Min 1, max 1440 (24h).	Integer

Exceeding the max_profiles limit of 5 returns CDP_LIMIT_REACHED: profile limit reached error. You can inspect and delete saved profiles directly in the Dashboard (hb.oxylabs.io/dashboard) if you hit the limit, or reuse one stable profile name. Contact Oxylabs support (live chat or email) or your Dedicated Account Manager if higher limits are required.

Reliable cross-session restore

For websites with strict bot monitoring systems, saving cookies is not enough. If a restored profile connects from a different residential exit IP, your cookies may get invalidated, resulting in blank pages or security verification screens.

To ensure consistent logins, pair your profile with a pinned residential exit IP:

// Session 1: Authenticate and back up state
const connectionOne = "wss://USER:[e-mail]?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";

// Session 2: Restore profile with the exact same IP session context
const connectionTwo = "wss://USER:[e-mail]?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";