Custom contexts are still in beta and may be incompatible with some versions of Chrome.

Browser cookies are stored in the user data directory. By default, Browserbase creates a new user data directory for each Session.

For some use cases (such as authentication), it can be helpful to preserve the user data directory and reuse it across sessions. With Contexts, it’s easy.

Sharing Contexts across Sessions

One benefit of using Contexts is that all the data generated during one session can be used in the next. This is especially useful to improve load times, as the network cache is also preserved.

Contexts are configured by creating a Context via the Contexts API.

Then, you’ll have to pass the Context’s ID to every Create Sessions API call.

Make sure to set context.persist to true when creating a Session if you want the Context to be updated with the Session’s state.

Here’s the steps:

To share Contexts across Sessions, follow these steps:

  1. Use the Contexts API to create a new context. You’ll need the context ID for the next step.
  2. Use the Sessions API to create a new session. You’ll need to add "browserSettings": { "context": { "id": YOUR_CONTEXT_ID, "persist": true } } to the body.

context.persist isn’t required for each Session. One workflow might involve having it enabled for the first Session (to fill the cache), and then disabling it on subsequent ones.

Context data can include stored credentials and other sensitive browsing data. Because of this, Contexts are uniquely encrypted at rest.

Uploading your own custom user data directory

In some scenarios, it may make sense to upload a custom user data directory. That’s why the Create Contexts API returns an authenticated uploadUrl that enables this. However, the file that’s uploaded must to follow a specific pattern in order to work with the Sessions.

  1. The uploaded context must have a filename of ${context.id}.zip
  2. The ZIP must be encrypted using details from the Context API response

Below is some sample code showing how to compress and encrypt a user data directory.

Handling Authentication

Once you set up Contexts, follow our authentication guide to easily log into websites.