---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/logins/stay-signed-in
markdown_url: https://steel.dev/docs/logins/stay-signed-in.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Stay signed in across sessions
description: Keep an agent signed in from one session to the next with a saved profile, and sign it in again when the site ends the login.
summary: Keep an agent signed in from one session to the next with a saved profile, and sign it in again when the site ends the login.
type: how-to
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/logins/browser-state.md
related:
  - https://steel.dev/docs/logins/browser-state.md
  - https://steel.dev/docs/logins/profiles.md
  - https://steel.dev/docs/logins/session-context.md
  - https://steel.dev/docs/logins/credentials.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Stay signed in across sessions

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](https://steel.dev/docs/logins/profiles), which [Browser state](https://steel.dev/docs/logins/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:

**TypeScript**

```sh
npm install steel-sdk playwright
```

**Python**

```sh
python3 -m venv .venv
source .venv/bin/activate
pip 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.

**TypeScript**

```ts file=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}`);
```

**Python**

```python file=save_login.py
import os
import time

from playwright.sync_api import sync_playwright
from steel import Steel

client = Steel()


def wait_until_ready(profile_id):
    deadline = time.monotonic() + 60
    while True:
        profile = client.profiles.get(profile_id)
        if profile.status == "READY":
            return profile
        if profile.status == "FAILED":
            raise RuntimeError(f"Steel could not save profile {profile_id}.")
        if time.monotonic() > deadline:
            raise RuntimeError(f"Profile {profile_id} is not ready after 60 seconds.")
        time.sleep(2)


session = client.sessions.create(persist_profile=True)
profile_id = session.profile_id

try:
    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(session.websocket_url)
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://steel.dev/practice/login")
        page.fill('input[name="username"]', os.environ["SITE_USERNAME"])
        page.fill('input[name="password"]', os.environ["SITE_PASSWORD"])
        page.click('button[type="submit"]')

        page.goto("https://steel.dev/practice/secure")
        if not page.locator("h3#username").is_visible():
            raise RuntimeError("The sign-in did not work")
        browser.close()
finally:
    client.sessions.release(session.id)

wait_until_ready(profile_id)
print(f"Saved profile {profile_id}")
```

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](https://steel.dev/practice/login) shows.

Run the program:

**TypeScript**

```sh
npx tsx save-login.mts
```

**Python**

```sh
python save_login.py
```

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

```text nocopy
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](https://steel.dev/docs/observability/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.

**TypeScript**

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

**Python**

```python
session = client.sessions.create(
    profile_id=os.environ["PROFILE_ID"],
    persist_profile=True,
)
```

**Go**

```go
import "os"

session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	ProfileID:      steel.F(os.Getenv("PROFILE_ID")),
	PersistProfile: steel.F(true),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        profile_id: Some(std::env::var("PROFILE_ID")?),
        persist_profile: Some(true),
        ..Default::default()
    })
    .await?;
```

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](https://steel.dev/docs/stealth/fingerprints#how-fingerprints-are-set) 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.

**TypeScript**

```ts
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"]');
}
```

**Python**

```python
page.goto("https://steel.dev/practice/secure")
if not page.locator("h3#username").is_visible():
    page.goto("https://steel.dev/practice/login")
    page.fill('input[name="username"]', os.environ["SITE_USERNAME"])
    page.fill('input[name="password"]', os.environ["SITE_PASSWORD"])
    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`:

**TypeScript**

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

**Python**

```python
session = client.sessions.create(
    profile_id=os.environ["PROFILE_ID"],
    credentials={},
)
```

**Go**

```go
import "os"

session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	ProfileID:   steel.F(os.Getenv("PROFILE_ID")),
	Credentials: steel.F(steel.SessionNewParamsCredentials{}),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        profile_id: Some(std::env::var("PROFILE_ID")?),
        credentials: Some(steel_rs::SessionCreateParamsCredentials::default()),
        ..Default::default()
    })
    .await?;
```

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](https://steel.dev/docs/logins/credentials#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](https://steel.dev/docs/logins/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](https://steel.dev/docs/logins/profiles#start-a-session-from-a-profile) 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

- [Credentials](https://steel.dev/docs/logins/credentials): Store the login in Steel, so that the session signs in and your code never needs the password.
- [Session context](https://steel.dev/docs/logins/session-context): Keep the cookies and storage in your own database instead of a profile.
- [Hand control to a human](https://steel.dev/docs/observability/hand-control-to-a-human): Let a person finish a sign-in step, such as a one-time code.
