Skip to content

Set timeouts

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 →

Two timeouts end a session that you did not release. timeout is the longest time that the session can live. inactivityTimeout ends it earlier when nothing drives the browser. Set both so that a crashed or stalled program does not leave a browser running longer than the task needs. Your plan sets the longest timeout that you can ask for.

Both values are in milliseconds, and you set them when you create the session. You cannot change them on a live session.

Before you begin

Put your Steel API key in the STEEL_API_KEY environment variable, and install the Steel SDK for your language: TypeScript, Python, Go or Rust.

Set the session timeout

timeout defaults to 300000, which is 5 minutes. When the time is up, Steel releases the session, even if your program still uses it. The shortest timeout is 15000. Steel raises a smaller value to 15000. In Python, the option is named api_timeout, because timeout sets the HTTP request's time limit. In Go and Rust, it is Timeout and timeout.

This program creates a session that can live for 10 minutes, prints its timeout, and releases it.

timeout.mts
import Steel from "steel-sdk";

const client = new Steel();
const session = await client.sessions.create({ timeout: 600000 });

try {
  console.log(session.timeout);
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx timeout.mts
600000

Ask for the time that the task needs, with a margin. A long timeout costs nothing when you release the session on time. The timeout sets the most that you pay when your program fails to release the session.

Release idle sessions

inactivityTimeout releases the session when it receives no activity for that long. Activity is a CDP command, a Commands request, or input from a person in the live view. These computer actions also count: move_mouse, click_mouse, drag_mouse, scroll, press_key and type_text. The other computer actions, such as take_screenshot and wait, do not. Each activity starts the count again. Without inactivityTimeout, a session stays alive until its timeout, even when nothing drives it.

This session can live for 10 minutes, and ends after 1 minute without activity:

const session = await client.sessions.create({
  timeout: 600000,
  inactivityTimeout: 60000,
});

Set inactivityTimeout lower than timeout. If it is equal or greater, it has no effect, because timeout ends the session first.

Time that your agent spends on a model call, or that a person spends reading the page, sends no activity to the browser. Choose a value that is longer than your task's longest pause.

Check that it worked

The session object has the timeouts that it runs with: timeout, and inactivityTimeout when you set one. The program in Set the session timeout prints 600000. To see inactivityTimeout work, create a session with it and do nothing in the session. Wait longer than that time, then read the session with sessions.retrieve (Sessions.Get in Go): its status is released, and its releaseReason is inactivity_timeout.

Defaults

The defaults depend on what creates the session:

Created bytimeoutinactivityTimeout
The API or an SDK5 minutesNone
The Steel CLI or the MCP server15 minutes. Change it with --timeout in the CLI, or timeout_minutes on session_create.10 minutes. In the CLI, change it with --inactivity-timeout.

Plan limits

The longest timeout depends on your plan. Limits lists the maximum session length for each plan. A request with a longer timeout fails, and no session is created. The response has the code session_timeout_exceeded. See Troubleshooting.

Troubleshooting

Read releaseReason on the session to learn why it ended. See Create a session for how to read it.

releaseReason is timeout

{ "status": "released", "releaseReason": "timeout" }

Cause: The session reached its timeout before your program released it. Steel released it, and your program's connection closed.

Fix: Create the session with a larger timeout, within your plan's maximum. If the task should have ended sooner, look for the step that waited, in the logs or agent traces.

Verify: Run the task again. When it is done, releaseReason is user_requested.

releaseReason is inactivity_timeout

{ "status": "released", "releaseReason": "inactivity_timeout" }

Cause: The session got no activity for the time in inactivityTimeout. This happens when the agent waits on a slow model call, when a computer-use agent only takes screenshots, or when a person does not act in time.

Fix: Raise inactivityTimeout above the task's longest pause, or leave it out.

Verify: Run the task again. When it is done, releaseReason is user_requested.

session_timeout_exceeded

{
  "error": "Bad Request",
  "code": "session_timeout_exceeded",
  "message": "Requested 'timeout' of 3600000 ms exceeds the maximum of 15 minutes on the launch plan. Set 'timeout' to 900000 or less, or upgrade your plan for longer sessions.",
  "param": "timeout",
  "retryable": false,
  "linkToDocs": "https://docs.steel.dev/overview/pricinglimits"
}

Cause: timeout is longer than your plan's maximum session length. The message names your plan and its maximum.

Fix: Set timeout to the value in the message or lower. For longer sessions, change your plan in Billing and usage.

Verify: Create the session again. The response has a session id.

Next steps