Guides / Guide
What is a browser session?
Separate the lifetime of a connection, a browser process, and an authenticated website session.
A browser session is a period during which an application can use a running browser and its state. In remote automation, the term is often used for three different lifetimes: the hosted browser allocation, the client's CDP connection, and the user's authenticated session on a website. Treating them as one lifetime causes confusing reconnect and login failures.
Three lifetimes to track
| Lifetime | Starts when | Can end when |
|---|---|---|
| Browser allocation | Infrastructure starts or assigns a browser | Explicit release, timeout, crash, or capacity policy |
| CDP connection | A client attaches to the browser | Client exit, disconnect, network interruption, or gateway closure |
| Website authentication | The website accepts a login | Logout, cookie expiry, server revocation, or additional verification |
A website can expire a login while the browser and connection remain healthy. A client can disconnect while the browser continues running, if the service permits it. Saving a profile can preserve some browser state after the process ends, but it cannot force the website to accept that state later.
What state belongs to a running browser?
The current page, JavaScript execution, pending requests, and unsaved form changes belong to the live runtime. Do not assume a profile restores them. Cookies and local storage can be persisted by an appropriate storage mechanism, with details depending on the provider and profile configuration.
Use persistent profile documentation to check the product's saved-state behavior. Design the workflow so it can detect an expired login and request authorized human assistance rather than repeatedly submitting credentials.
Reconnect deliberately
After a connection failure, first ask whether the allocation still exists. If it does, reattach and inspect the current page. A prior click might have succeeded even though its response never reached the client. Retrying a purchase, publication, or form submission without inspecting the result can duplicate the action.
Record a session identifier and task identifier separately. Store checkpoints describing what the task has verified, without logging secrets or full endpoint URLs. For workflows with side effects, verify the site's confirmation state before proceeding.
End sessions explicitly
Assign one component responsibility for cleanup. Stopping a worker is not a reliable substitute for releasing a browser allocation. Check the service's release mechanism, idle timeout, and metering policy, then handle success, failure, and cancellation paths.
Use session lifecycle design for an allocation state model and browser-hour measurement to understand how idle time affects cost. If multiple workers need the same account, also define profile ownership and session isolation.