Session Lifecycle

Overview

Sessions are the foundation of browser automation in Steel. Each session represents an isolated browser instance that persists until it's either explicitly released or times out.

Each session can be in one of three states:

• Live: The session is active and ready to accept commands/connections. This is the state right after creation and during normal operation.

• Released: The session has been intentionally shut down, either through explicit release or timeout. Resources have been cleaned up. Can no longer accept commands/connections.

• Failed: Something went wrong during the session's lifetime (like a crash or connection loss). These sessions are automatically cleaned up.

Browser sessions are billed and metered by the minute. A session can last up to 24 hours depending on your plan.

Understanding how sessions live and die helps you manage resources effectively and build more reliable applications.

Reserving a Session ID

Steel generates a session ID for you, but create also accepts one. Pass your own UUID when the ID has to exist before the browser does: a job row you write before starting the session, or a live view link you hand to a user while the browser is still booting.

1
import { randomUUID } from 'node:crypto';
2
import Steel from 'steel-sdk';
3

4
const client = new Steel();
5

6
// Reserve the ID first, then create the session with it.
7
const sessionId = randomUUID();
8
await jobs.insert({ sessionId, status: 'starting' });
9

10
const session = await client.sessions.create({ sessionId });
11
console.log(session.id === sessionId); // true

The value must be a valid UUID such as 123e4567-e89b-12d3-a456-426614174000. Omit sessionId and Steel generates one instead. Either way, the ID goes to the same places:

• client.sessions.release(sessionId) to end the session

• client.sessions.files.list(sessionId) and the rest of the Files API

• wss://connect.steel.dev?apiKey=<key>&sessionId=<id> to attach Playwright or Puppeteer

Session Lifetime and Timeout

When you start a session, it stays alive for 5 minutes by default but you can change it by passing the timeout parameter. After the time passes, the session will be automatically released.

1
import Steel from 'steel-sdk';
2

3
const client = new Steel();
4

5
// Create session and keep it running for 10 minutes.
6
const session = await client.sessions.create({
7
  timeout: 600000 // 10 minutes (NOTE: Units are in milliseconds)
8
});

Note: Currently, Steel doesn’t support editing the timeout duration of a live session.

Inactivity Timeout

By default a session runs until its timeout elapses, even when nothing is driving the browser. Set inactivityTimeout to release the session early once it stops seeing activity—any CDP command or remote input—so you don’t keep paying for an idle browser while waiting on an external step.

1
import Steel from 'steel-sdk';
2

3
const client = new Steel();
4

5
// Release the session after 1 minute with no CDP or input activity,
6
// capped at a 10-minute hard limit.
7
const session = await client.sessions.create({
8
  timeout: 600000,          // 10 minutes (hard cap)
9
  inactivityTimeout: 60000, // release after 1 minute of inactivity
10
});

Note: timeout is always the hard cap on a session’s lifetime. If inactivityTimeout is greater than or equal to timeout it has no effect—timeout elapses first. Omit inactivityTimeout to disable inactivity-based release (the default).

Releasing a Session

When you're done with a session, it's best practice to release it explicitly rather than waiting for the timeout. You can release a session any time before the timeout is up by calling the release method.

1
// Release a single session
2
const response = await client.sessions.release(session.id);

Bulk Session Release

Sometimes you need to clean up all active sessions at once. Steel provides a convenient way to do this:

1
// Release all active sessions
2
const response = await client.sessions.releaseAll();
3
console.log(response.message); // "All sessions released successfully"

FAQ