Skip to content

Session lifecycle

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 session lasts from its creation until you release it, one of its timeouts passes, or its browser stops. Steel bills the browser for that time, so a session that you forget keeps costing money until a timeout ends it.

States

A session's status is one of these values:

StatusMeaning
liveThe browser runs. You can connect to it, send commands and watch it.
releasedThe session ended. You released it, a timeout passed, or the browser closed or crashed. releaseReason says which.
failedSteel could not start the browser. releaseReason is startup_failed or creation_timeout.

A session is live after sessions.create returns. It then moves once, to released, and never returns to live. To keep working, create a new session. When Steel cannot start the browser, sessions.create returns an error. Steel can keep a record of the attempt, as a session with the status failed.

A crash does not make a session failed. To find the sessions whose browser crashed, list sessions with releaseReason set to browser_crashed.

sessions.list leaves out failed sessions unless you ask for them by status or releaseReason. Create a session shows how to list and filter sessions.

How a session ends

Each released or failed session has a releaseReason that says why it ended. It is null while the session is live. It can also be null after a session ends, when Steel has no record of why it ended, as for sessions from before Steel recorded reasons.

releaseReasonWhat ended the session
user_requestedYou released it through the API or SDK.
timeoutIt reached its timeout.
inactivity_timeoutIt had no activity for its inactivityTimeout.
creation_timeoutIt did not start in time.
startup_failedSteel could not start the browser.
browser_closedThe browser or agent closed itself. This is not a crash.
browser_crashedThe browser crashed, or its machine stopped responding.

Release a session as soon as the work is done. sessions.release ends one session, and sessions.releaseAll (release_all in Python) ends every live session that your API key can reach. See Release all sessions. Release a session in a finally block, so that it ends even when your code fails. A release of a session that already ended returns Session already released.

Timeouts

Two timeouts end a session that you do not release. You set both when you create the session, in milliseconds. You cannot change them on a live session.

  • timeout is the longest that the session can live. Set timeouts has its default, and Limits has the maximum for each plan.
  • inactivityTimeout ends the session early when nothing drives it for that long. A CDP command, a Commands request, input from the live view and most computer actions count as activity. Release idle sessions lists them. The option has no default. Without it, an idle session runs until its timeout.

In the Python SDK, the options are api_timeout and inactivity_timeout. A session timeout passed as timeout in Python is deprecated, because timeout there sets the HTTP request's timeout.

timeout is always the hard limit. An inactivityTimeout that is equal to timeout or longer has no effect.

Set inactivityTimeout when your code can stop without a release, for example when an agent hangs. The session then ends once it has been idle for its inactivityTimeout, not at the end of its timeout. The MCP server and the Steel CLI set an inactivityTimeout on the sessions that they create. Set timeouts lists their defaults.

Set timeouts shows how to set both.

What you pay for

Steel bills browser time for a session from its start until it ends. The billed time never goes past the session's timeout. The rate depends on your plan, and Pricing has it.

A session can also add charges for Steel proxy bandwidth and for each CAPTCHA that Steel solves. Steel adds up the final cost after the release. Session cost shows how to read it.

The cheapest session is one that ends as soon as its work is done. Release it explicitly, and use inactivityTimeout as a safety net.

What remains after release

A released session has no browser, so a request that needs the browser fails. You cannot connect over CDP, send commands or read the session context. A Commands request returns 410 with session_ended.

The session itself stays, with its id, its status and its releaseReason. Some data becomes available only after the release:

  • The session cost is final once Steel records the usage.
  • The signals appear a few seconds after the session ends.
  • A profile that the session saved becomes ready to load.

The recording, logs, agent traces and files stay too. About Steel lists what each one holds. Limits says how long Steel keeps them.