Skip to content

Profiles

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 →

A profile saves a session's whole browser in Steel: its cookies, storage, extensions, settings and user agent. A later session that starts from the profile gets the same cookies and storage, so it stays signed in until the site ends the login. Open tabs do not carry over. Use a profile when sessions should pick up where the last one stopped. Browser state lists what carries over, and compares a profile with session context, which you store yourself, and credentials, which sign in for your agent.

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

In Go and Rust, install only the SDK, as the Go and Rust SDK pages show. The code that drives the browser uses Playwright, so it is in TypeScript and Python only.

Save a profile

Set persistProfile to true when you create the session. The response has a profileId at once, but Steel saves the browser only after you release the session. The profile has the status UPLOADING until the save is done, and then READY.

This program creates a session that saves a profile, stores a value in localStorage, and releases the session. Then it reads the profile every 2 seconds until it is READY, and prints its ID. It stops with an error if Steel could not save the profile, or if the profile is not ready after 60 seconds.

save-profile.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();

async function waitUntilReady(profileId: string) {
  const deadline = Date.now() + 60_000;
  for (;;) {
    const profile = await client.profiles.get(profileId);
    if (profile.status === "READY") return profile;
    if (profile.status === "FAILED") throw new Error(`Steel could not save profile ${profileId}.`);
    if (Date.now() > deadline) throw new Error(`Profile ${profileId} is not ready after 60 seconds.`);
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
}

const session = await client.sessions.create({ persistProfile: true });

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://example.com");
  await page.evaluate(() => localStorage.setItem("theme", "dark"));
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

const profile = await waitUntilReady(session.profileId!);
console.log(profile.id, profile.status);

Run the program:

npx tsx save-profile.mts

The program prints the profile's ID and status. Keep the ID, because the next sections use it.

f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 READY

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

Besides the browser, a profile saves the userAgent, dimensions, useProxy, extensionIds and credentials of the session that created it.

Start a session from a profile

Pass the ID of a READY profile in profileId. The session starts with the saved browser.

This program starts a session from the profile and reads the value that the first session stored.

use-profile.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();
const session = await client.sessions.create({
  profileId: process.env.PROFILE_ID,
});

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://example.com");
  console.log(await page.evaluate(() => localStorage.getItem("theme")));
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

Run the program with the ID that the first program printed:

PROFILE_ID=f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 npx tsx use-profile.mts

The program prints the value from the first session.

dark

A session that starts from a profile does not change the profile. To save the session's changes, see Update a profile. If the request sets userAgent, dimensions or useProxy, the session uses the request's value instead of the profile's.

A profile keeps the browser, not the IP address. Some sites ask for a new login when an account appears from a new address. To keep the address too, use the profile with a dedicated IP.

Update a profile

To save a session's changes back into its profile, pass persistProfile: true with profileId. When you release the session, Steel replaces the saved browser with this session's browser. The profile stays READY during the update, and its updatedAt changes when the save is done.

const session = await client.sessions.create({
  profileId: process.env.PROFILE_ID,
  persistProfile: true,
});

Use one profile for each account, and do not run two sessions that save the same profile at the same time. Both start from the same browser, and the session that you release last replaces the other's changes.

You can also replace the saved browser with a browser profile directory of your own, as a zip file of at most 300 MB. Send it in userDataDir to client.profiles.update. You can change userAgent, dimensions and useProxy in the same call. Steel does not save proxyUrl in a profile.

import { createReadStream } from "node:fs";

const profile = await client.profiles.update(process.env.PROFILE_ID!, {
  userDataDir: createReadStream("profile.zip"),
});

To create a new profile from a zip file, call client.profiles.create with the same fields. The Profiles API lists every field.

List profiles

client.profiles.list returns the profiles of your project and their count, the most recently updated first. Each profile has its id, its status, and the times it was created and last updated.

const { profiles, count } = await client.profiles.list();
console.log(count);
for (const profile of profiles) {
  console.log(profile.id, profile.status);
}

The code prints the count, then one line for each profile. In a project with 980 profiles, the output starts like this:

980
f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254 READY
52bb1668-ce32-4229-8698-2b269294e76d READY

To read one profile, call client.profiles.get with its ID.

Steel deletes a profile that no session has used for 30 days. The API has no call to delete a profile. To remove a login from a profile now, start a session from the profile with persistProfile: true, sign out of the site or clear its cookies, and release the session. Steel then saves the profile without the login. To have a profile deleted, contact Support.

Check that it worked

Read the profile with client.profiles.get (client.Profiles.Get in Go). A saved profile has the status READY. Then start a session from it, as Start a session from a profile shows. The session has what the first session stored, such as the localStorage value dark that the program prints.

Troubleshooting

profile_not_ready

{
  "error": "Conflict",
  "code": "profile_not_ready",
  "message": "Profile 'f1a9c2f5-75a2-4cdd-99aa-2caa15bc4254' is not ready yet. It is saved after session 'c1876bc5-6d4d-4e32-a270-1565b9f91281' is released. If that session is still running, release it (POST /v1/sessions/c1876bc5-6d4d-4e32-a270-1565b9f91281/release), then retry in 5 seconds.",
  "param": "profileId",
  "retryable": true,
  "retryAfterSeconds": 5,
  "linkToDocs": "https://docs.steel.dev/overview/sessions-api/reusing-auth-context"
}

Cause: The profile has the status UPLOADING. The session that saves it is still running, or Steel is still saving it.

Fix: Release the session that the message names. Wait until the profile is READY, as the program in Save a profile does.

Verify: client.profiles.get returns the status READY, and the new session starts.

profile_upload_failed

{
  "error": "Unprocessable Entity",
  "code": "profile_upload_failed",
  "message": "Profile 'PROFILE_ID' failed to upload and cannot be used. Create a new profile and reference that one instead.",
  "param": "profileId",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/sessions-api/reusing-auth-context"
}

Cause: Steel could not save the profile, and its status is FAILED. A profile larger than 300 MB fails this way.

Fix: Create a new profile, and keep it at 300 MB or less.

Verify: The new profile reaches the status READY.

profile_not_found

{
  "error": "Not Found",
  "code": "profile_not_found",
  "message": "Profile '8c6468ce-89ca-4368-ab09-dbd96909bf19' not found. It may have expired (profiles have a TTL) or belong to a different organization. Check the id, or create a new profile.",
  "param": "profileId",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/sessions-api/reusing-auth-context"
}

Cause: The ID is wrong, the profile belongs to another organization or project, or Steel deleted it after 30 days without use.

Fix: Check the ID with client.profiles.list. If the profile is gone, save a new one.

Verify: client.profiles.get returns the profile.

Next steps