Skip to content

Session context

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

Session context is a running session's cookies and storage, as a JSON object that you export and keep yourself. You pass it to a new session, which starts with the same cookies and storage, and so with the same logins. Use session context when your application must hold the state itself, for example in its own database. Browser state compares it with a profile, which Steel stores for you, and credentials, which sign in for your agent.

Session context works for sites that keep the login in cookies, localStorage, sessionStorage or IndexedDB. The new session restores a site's storage when it opens a page on that site.

Before you begin

Put your Steel API key in the STEEL_API_KEY environment variable. Then install the Steel SDK and Playwright.

npm install steel-sdk playwright

Export the context

Call client.sessions.context with the session's ID. You can export the context only while the session runs, so export it before you release the session.

This program signs in to Steel's practice site, exports the context to context.json, and releases the session. Set SITE_USERNAME and SITE_PASSWORD to the test login that the site's sign-in page shows.

export-context.mts
import { writeFile } from "node:fs/promises";
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();
const session = await client.sessions.create();

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const browserContext = browser.contexts()[0];
  const page = browserContext.pages()[0] ?? (await browserContext.newPage());
  await page.goto("https://steel.dev/practice/login");
  await page.fill('input[name="username"]', process.env.SITE_USERNAME!);
  await page.fill('input[name="password"]', process.env.SITE_PASSWORD!);
  await page.click('button[type="submit"]');
  await page.waitForURL("**/secure");

  const context = await client.sessions.context(session.id);
  await writeFile("context.json", JSON.stringify(context));
  console.log(`Saved ${context.cookies?.length ?? 0} cookies`);
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx export-context.mts

The program writes the context to context.json and prints how many cookies it holds. The next section reads that file, and What a context holds describes its fields.

Saved 1 cookies

To save a login, sign in during this session, with your code or by hand in the live view. Before you export the context, open a page that only a signed-in user can see, to check that the login worked.

Start a session with a context

Pass the context in sessionContext when you create the session. Without sessionContext, a session starts with an empty context.

This program reads context.json, starts a session with it, and opens a page that only a signed-in user can see.

use-context.mts
import { readFile } from "node:fs/promises";
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();
const sessionContext = JSON.parse(await readFile("context.json", "utf8"));
const session = await client.sessions.create({ sessionContext });

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://steel.dev/practice/secure");
  console.log(page.url());
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx use-context.mts

The program prints the page's URL. The new session is signed in, so the site shows the page. Without the context, the site sends the browser to its sign-in page.

https://steel.dev/practice/secure

A context is a copy from one moment. What the new session changes does not reach your context.json. To keep the new state, export the context again before you release the session.

A site can still ask for a new login, for example when the login has expired or when the account appears from a new IP address. Like a profile, a context does not keep the address. Profiles explains how to keep it with a dedicated IP.

Check that it worked

Run the program in Start a session with a context. It prints https://steel.dev/practice/secure, so the site accepts the login from context.json. To see the difference, remove sessionContext (session_context in Python) from the program and run it again. That session has no login, so the program prints the sign-in page's URL, https://steel.dev/practice/login.

What a context holds

FieldWhat it holds
cookiesA list of cookies. Each cookie has a name and a value, and can have domain, path, expires, httpOnly, secure, sameSite and other attributes.
localStorageThe localStorage items, grouped by domain: an object that maps each domain to its keys and values.
sessionStorageThe sessionStorage items, grouped by domain in the same way.
indexedDBThe IndexedDB databases, grouped by domain: for each domain, a list of databases with their object stores and records.

You can edit the object before you pass it, for example to remove a site's cookies. A context does not hold the rest of the browser, such as its extensions, settings or history. For those, use a profile. The Sessions API has the full schema.

Troubleshooting

Session is not live, so its context cannot be read

{
  "error": "Not Found",
  "message": "Session 'SESSION_ID' is not live, so its context cannot be read. Context is only available while a session is running — create a new session or check its status first.",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/sessions-api/session-lifecycle"
}

Cause: The session has ended. Steel does not keep a released session's context.

Fix: Export the context before you release the session, as the program in Export the context does. If the session ended on its timeout, set a longer timeout.

Verify: client.sessions.context returns an object with cookies.

Next steps

  • Credentials: Sign in again when the cookies in a context no longer work.