Skip to content

Stay signed in across sessions

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 →

Each session starts as a new browser with no cookies, so a site asks your agent to sign in again. To skip that step, carry the login from one session to the next. You sign in once, start the next session from the saved state, and sign in again when the login expires. The steps below use a profile, which Browser state compares with session context and credentials.

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

1. Sign in once and save a profile

Set persistProfile to true when you create the session. Steel creates a profile and returns its ID in profileId. When you release the session, Steel saves the browser's data to the profile.

This program signs in once on Steel's practice site and saves the login to a profile.

save-login.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 });
const profileId = session.profileId!;

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/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.goto("https://steel.dev/practice/secure");
  if (!(await page.locator("h3#username").isVisible())) {
    throw new Error("The sign-in did not work");
  }
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

await waitUntilReady(profileId);
console.log(`Saved profile ${profileId}`);

The program checks that the login worked and releases the session. Then it reads the profile every 2 seconds until it is READY. It stops with an error if Steel could not save the profile, or if the profile is not ready after 60 seconds. For your own site, change the URLs and selectors.

To run it as it is, set SITE_USERNAME to tomsmith and SITE_PASSWORD to SuperSecretPassword!, the demo account that the site's sign-in page shows.

Run the program:

npx tsx save-login.mts

The program prints the profile's ID. Keep it with the account that it belongs to, in your database or in an environment variable.

Saved profile 52bb1668-ce32-4229-8698-2b269294e76d

Check a page that only a signed-in user can open, as the program does. A filled password field does not prove that the sign-in worked. If the sign-in needs a code from a phone or a CAPTCHA that a person must solve, let a person do that step in the live view. Hand control to a human shows how.

2. Start the next session from the profile

Pass the ID in profileId. The session starts with the profile's cookies and storage, so the site sees a browser that is already signed in. Set persistProfile to true again to save what changes in this session, such as a cookie that the site renews.

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

Leave out persistProfile when a run must not change the profile.

Steel saves a profile after the session that writes it is released. If you start a session from a new profile that is still being saved, the API returns 409 with the code profile_not_ready. The error is retryable. By default, the Steel SDK waits for the time in the Retry-After header and tries again, up to twice. A profile that a session updates stays READY, and its updatedAt changes when the save is done. A session that starts before then gets the state from before the update.

A session that starts from a profile keeps the profile's user agent, and Steel injects no other fingerprint values into it, as Fingerprints explains.

Give each account its own profile, and run one session at a time for each profile that you write. Two sessions that write the same profile start from the same state, and the session that is released last overwrites the other's changes.

3. Handle a login that expired

A site can sign you out at any time: after a fixed number of days, after a password change, or when it sees a new device or IP address. A saved profile does not prevent that. Check the login at the start of each run, and sign in again when it is gone.

await page.goto("https://steel.dev/practice/secure");
if (!(await page.locator("h3#username").isVisible())) {
  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"]');
}

When the session was created with persistProfile: true, the new login goes into the profile when you release the session. The next run starts signed in again.

To keep the password out of your agent's code and prompts, store it as a credential instead. Credentials are in Beta. Steel fills the sign-in form when the page shows one, and blurs the username and password on the screen after it fills them. Your code and your agent never need the password, and Steel never returns it. Code that reads the page can still read a filled field. Add credentials to a session that loads the profile, and leave out persistProfile:

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

This session does not save the new login to the profile, so Steel signs in again in each run that finds the login gone. Use credentials with a profile explains why the session must not save the profile. To put a new login in the profile, sign in with your code in a session that saves the profile, as above. Credentials shows how to store the credential, and how to match it to a session with a namespace.

If the site asks for a step that code cannot do, such as an approval on a phone, hand the session to a person. Do it in a session that saves the profile, created with persistProfile: true, then release it, so that Steel saves the result to the profile. A session with credentials does not save the profile, so a sign-in that a person finishes there lasts only for that session.

If the site still asks for a new sign-in on each run, it may react to a new IP address each time. A profile keeps the address only when the session uses a dedicated IP, as Profiles explains.

Check that it worked

Start a new session from the profile, and open https://steel.dev/practice/secure. The page shows the secure area with the username, not the sign-in page, so the login carried over. On your own site, open a page that only a signed-in user can see.

Next steps