Browser state
Browser state is what a browser remembers about the sites it visits: cookies, local storage, a login. A new Steel session starts with none of it. When the session ends, its state goes away unless you saved it. To carry state into a session, use a profile, a session context or credentials (Beta). Each keeps a different part.
Compare profiles, session context and credentials
| Profile | Session context | Credentials | |
|---|---|---|---|
| What it holds | The whole browser profile: cookies, storage, extensions and settings, with the browser's user agent | Cookies, local storage, session storage and IndexedDB | A login for one website: a username, a password and other values |
| Who stores it | Steel, in your project | You, in your own storage | Steel, encrypted, in your project |
| How a session gets it | profileId | sessionContext | credentials, and the session's namespace |
| Use it to | Keep one account signed in, as the same browser, run after run | Copy a known set of cookies and storage into a session | Let Steel sign in for the agent, so your code and the agent never need the password |
You can use more than one in a session. For example, a profile keeps the login, and credentials sign in again when the site asks. For now, do not save the profile from a session that uses credentials. Use credentials with a profile explains why.
Profiles
A profile is a saved copy of a browser's user data directory. It holds what the browser holds on disk: cookies, storage, extensions and settings. It also keeps the session's user agent and window size. A session that starts from the profile uses that user agent and gets no other fingerprint values from Steel.
A session saves a profile when you create the session with persistProfile. The profile is UPLOADING while the session runs, and Steel saves the browser's data when the session ends. Then the profile is READY. A later session loads it with profileId. To save that session's changes back to the profile, set persistProfile again.
Use one profile for one account. Two sessions that load the same profile start from the same state, and their changes can conflict when both save. Run the sessions that save to a profile one after the other.
A profile belongs to one project. Steel limits a profile's size and how long it keeps an unused one. Profiles has the numbers.
Session context
A session context is the state of a live session as data: its cookies, local storage, session storage and IndexedDB. You read it from a session while the session runs, and you pass it in sessionContext when you create another session. The new session starts with that state.
Steel does not keep the context for you. Your app stores it, so you choose what to keep and where. You can also edit it, for example to pass only one site's cookies.
A context holds less than a profile. A site that checks the browser as well as its cookies and storage can ask you to sign in again. When you pass both a profile and a sessionContext, the sessionContext replaces the profile's context.
A context can hold an active login. Protect it as you protect a password.
Credentials
A credential is a login that Steel stores for one website origin, such as https://app.example.com. Steel encrypts it. When a session that uses credentials opens a sign-in page on that origin, Steel fills the form and, by default, submits it. Steel never returns the stored password, and your code and the agent never need it. Snapshots mask it, but code that reads the page can still read a filled field.
Steel stores each credential in a project and a namespace. A session uses only the credentials in its own project and namespace, and the match is exact. Namespaces let you keep a login for each of your users on the same site. Projects and namespaces explains how they nest.
A credential does not keep a session signed in. It signs in again each time the site shows its sign-in form. It can hold a TOTP secret for one-time codes, but it cannot answer a check that the site sends to a person, such as a code by email.
What is not kept
When a session ends, Steel discards the browser. These things do not carry over to the next session:
- Open tabs and the state of each page. A session that loads a profile starts a new browser from the saved data. It does not reconnect to the old session.
- Changes after the last save. A session that loads a profile without
persistProfiledoes not write its changes back. - The IP address. A profile keeps the proxy setting, not the address that sites saw, unless the proxy is a dedicated IP. Profiles explains how to keep the address.
- The site's trust. A site decides how long a login lasts. It can sign you out, or ask to verify the device, even when you restore the state.
Files are separate from browser state. The Files API keeps a session's files after it ends.