Configure a Browser Session

Use this guide to select stable, non-experimental session settings for a browser task. Start with no optional settings. Add only the settings that the task needs.

Start with the minimum

1
import Steel from 'steel-sdk';
2

3
const client = new Steel({
4
  steelAPIKey: process.env.STEEL_API_KEY,
5
});
6

7
const session = await client.sessions.create();

Steel creates a desktop, headful session with a default timeout of 5 minutes. A headful session has a visible browser window. By default, Steel does not use a proxy or solve CAPTCHAs.

Choose a configuration

Recipes

Select the recipe that is closest to your task. Remove any setting that the task does not need.

Find a setting

If you know the browser behavior that the task needs, use this table.

useProxy accepts true, false, or a configuration object. Properties such as geolocation are part of the useProxy object.

Common configurations

Each recipe below is a JSON request body with only the settings for its task. Save a recipe as session.json. Send the file to POST /v1/sessions with curl.

1
curl https://api.steel.dev/v1/sessions \
2
  -H "steel-api-key: $STEEL_API_KEY" \
3
  -H "Content-Type: application/json" \
4
  -d @session.json

@session.json tells curl to read the request body from that file. For supported TypeScript SDK settings, pass the same object to client.sessions.create(...). If the SDK type does not include a setting, use the REST API for that recipe.

Task with an inactivity timeout

If Steel must release an idle session before timeout, use this recipe. Steel releases the session after 1 minute without a Chrome DevTools Protocol (CDP) command or remote input.

1
{
2
  "timeout": 600000,
3
  "inactivityTimeout": 60000
4
}

This request sets timeout to 10 minutes. Activity resets the 1-minute inactivity timer.

Long-running headless worker

If an unattended task can run for several minutes, use this recipe. Steel releases the session after 2 minutes without a CDP command or remote input.

1
{
2
  "headless": true,
3
  "timeout": 900000,
4
  "inactivityTimeout": 120000
5
}

The task can run for up to 15 minutes. Activity resets the 2-minute inactivity timer.

Text extraction on a protected site

If the task needs a residential IP and automatic CAPTCHA solving, use these settings. Your account must have access to these features.

1
{
2
  "useProxy": true,
3
  "solveCaptcha": true,
4
  "optimizeBandwidth": {
5
    "blockImages": true,
6
    "blockMedia": true,
7
    "blockStylesheets": false
8
  }
9
}

This recipe keeps stylesheets because they can affect page behavior. Remove each setting that the task does not need.

CAPTCHA detection with human control

If Steel must detect a supported CAPTCHA and a person must respond in the live viewer, use this recipe. Your account must have access to CAPTCHA solving.

1
{
2
  "solveCaptcha": true,
3
  "stealthConfig": {
4
    "autoCaptchaSolving": false
5
  },
6
  "debugConfig": {
7
    "interactive": true
8
  }
9
}

Steel detects the CAPTCHA without solving it automatically. The live viewer accepts input because the session is interactive. Protect the debug URL before you share it.

Account task without saved changes

If the task needs profile state without saving changes, use this recipe. Before you use the recipe, confirm that the profile status is READY. Replace the example UUID with a profile UUID from your workspace.

1
{
2
  "profileId": "123e4567-e89b-12d3-a456-426614174000"
3
}

Steel restores the profile state for the session. Because the request omits persistProfile, Steel does not save the session's profile changes after release.

Account task with stored state

Before you use these settings, confirm that the profile status is READY. Replace the example profile UUID with a profile UUID from your workspace. Replace the example dedicated IP ID with an ID from your workspace.

1
{
2
  "profileId": "123e4567-e89b-12d3-a456-426614174000",
3
  "persistProfile": true,
4
  "useProxy": {
5
    "type": "fixed",
6
    "id": "fixed:8SdfYs77me"
7
  }
8
}

This recipe restores stored browser state. Steel saves the new browser state after you release the session. The recipe also uses one dedicated IP.

Mobile task in a selected country

If the site must show its mobile version for a selected country, use these settings. Your account must have access to Steel-provided proxies.

1
{
2
  "deviceConfig": {
3
    "device": "mobile"
4
  },
5
  "useProxy": {
6
    "geolocation": {
7
      "country": "DE"
8
    }
9
  }
10
}

The mobile setting controls the browser fingerprint and input behavior. The proxy setting controls the public IP location.

Setting reference

The following sections explain stable session settings by topic. Use Find a setting to open a section.

Session life

Use these settings to control the total and idle session life.

CDP commands and remote input reset the inactivity timer. After the task is complete, release the session. See Session Lifecycle for session states and release methods.

Network identity

Use the smallest location scope that the task needs.

• region selects the location of the browser process. Proxy geolocation selects the public IP location that the site receives.
• If you load a profile, useProxy: false overrides the proxy setting in that profile.
• proxyUrl overrides useProxy. Use only one custom proxy method in a session request.

See Multi-Region Sessions, Proxies, and Dedicated IPs.

Stored state

Select the state methods that the task needs.

You can use more than one state method in a session. A request-level sessionContext replaces the profile session context. A request-level credentials object replaces the profile credentials.

Save changes in a profile

To create a profile from a session, set persistProfile to true. Before you use the new profile, complete these steps:

1. 1Copy profileId from the first session response.
2. 2Complete the browser task.
3. 3Release the first session.
4. 4Wait until the profile status is READY.
5. 5Create the next session with profileId.
6. 6If the next session must save its changes, set persistProfile to true.

Profile and credential rules:

• The API returns 409 if the profile status is UPLOADING.
• A profile UUID must identify a profile in the same project.
• Stored credentials must use the same project and namespace as the session.
• The credentials object can submit stored values automatically, blur credential fields, and require an exact origin match.

See Profiles, Reusing Auth Context, and Credentials.

Browser interface

Use these settings to select the window size, mobile identity, or display mode.

Steel rejects custom mobile dimensions below 508×1074 (width × height). Use mobile mode for a complete mobile browser identity. See Mobile Mode and Fullscreen Mode.

Page support

Set solveCaptcha to true to detect and solve supported CAPTCHA types. Use this recipe to detect a CAPTCHA without automatic solving:

1
{
2
  "solveCaptcha": true,
3
  "stealthConfig": {
4
    "autoCaptchaSolving": false
5
  }
6
}

• Set stealthConfig.humanizeInteractions to true to simulate human pointer movements and keystrokes.
• If the task controls the browser fingerprint, set stealthConfig.skipFingerprintInjection to true.
• For all other tasks, omit stealthConfig.skipFingerprintInjection.

See CAPTCHA Solving for automatic and manual solve methods.

Resource control

Steel does not block ads by default. Use resource settings only when the task needs different behavior.

Block only the resources that the task does not use. If the task uses screenshots or visual analysis, do not block images. If layout or visibility is important, do not block stylesheets.

Viewer and connection

Use these settings to control the viewer and browser connection.

The viewer URL cannot make a read-only session interactive.

See Live Sessions, Human-in-the-Loop Controls, and Selenium.

Project context

Use projectId and namespace only to select a different project context. Stored credentials must use the same project and namespace as the session. For exact request types and validation rules, see the API Reference.