---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/sessions/configuration
markdown_url: https://steel.dev/docs/sessions/configuration.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Session configuration
description: Set up a new session with these options. Each one has its type, its default and a link to the page that explains it.
summary: Look up every option that a new session takes, with its type and default.
type: configuration
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/sessions/lifecycle.md
related:
  - https://steel.dev/docs/sessions.md
  - https://steel.dev/docs/sessions/lifecycle.md
  - https://steel.dev/docs/sessions/timeouts.md
  - https://steel.dev/docs/sessions/devices.md
  - https://steel.dev/docs/sessions/metadata.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Session configuration

Session options are the fields of the create-session request, `POST /v1/sessions`. They set how the session's browser runs, such as its timeout, its proxy and the profile that it starts from. With a project key, every option is optional, and a request with no body creates a session with the defaults. With an organization key, the request must include `projectId`. The types and defaults come from the API specification. The response fields are on [Sessions API](https://steel.dev/docs/reference/api/sessions#create-a-session).

The TypeScript SDK uses the names on this page. The Python SDK writes the same names in snake_case, in nested objects too. For example, `useProxy` is `use_proxy`, and `stealthConfig.autoCaptchaSolving` is `stealth_config.auto_captcha_solving`. Only `timeout` is different. It is `api_timeout` in Python, because `timeout` is the timeout of the HTTP request there. Pass the session timeout as `api_timeout`, not as `timeout`.

## Sessions

| Option | Type | Default | What it does | Page |
| - | - | - | - | - |
| `blockAds` | boolean | `true` | Blocks requests to known ad and tracking hosts. Set it to `false` to let them load. | [Reduce bandwidth](https://steel.dev/docs/sessions/bandwidth) |
| `concurrency` | integer | None | Ignored. One request creates one session. | [Know your limits](https://steel.dev/docs/production/run-sessions-at-scale#know-your-limits) |
| `deviceConfig` | object | `{"device": "desktop"}` | Whether the browser presents itself as a desktop or a mobile device. See [deviceConfig](https://steel.dev/docs/sessions/configuration#deviceconfig). | [Set the device and viewport](https://steel.dev/docs/sessions/devices) |
| `dimensions` | object | 1920 × 1080 | The size of the browser window, in pixels, at most 1920 × 1080. In a headful desktop session, the page's viewport is 8 pixels narrower and 91 pixels shorter. See [dimensions](https://steel.dev/docs/sessions/configuration#dimensions). | [Set the device and viewport](https://steel.dev/docs/sessions/devices) |
| `experimentalFeatures` | string array | None | Turns on features by name. `["useStealthBrowser"]` runs the session on Stealth Browser. The other names, which Steel does not publish, turn on [Experimental](https://steel.dev/docs/platform/release-stages) features. | [Stealth Browser](https://steel.dev/docs/stealth/stealth-browser) |
| `fullscreen` | boolean | `false` | Hides the browser's address bar and toolbars, so that the page fills the whole screen of 1920 × 1080. It ignores `dimensions`. | [Set the device and viewport](https://steel.dev/docs/sessions/devices) |
| `headless` | boolean | `false` | Runs the browser in headless mode. By default, the session is headful, with a visible browser window. | [Create a session](https://steel.dev/docs/sessions) |
| `inactivityTimeout` | integer | None | Releases the session after this many milliseconds without activity, such as a CDP command or a Commands request. [Release idle sessions](https://steel.dev/docs/sessions/timeouts#release-idle-sessions) lists what counts as activity. The minimum is 1. It has no effect when it is equal to or greater than `timeout`. | [Set timeouts](https://steel.dev/docs/sessions/timeouts) |
| `metadata` | object | `{}` | Your own key-value pairs for the session. See [metadata](https://steel.dev/docs/sessions/configuration#metadata). | [Add metadata](https://steel.dev/docs/sessions/metadata) |
| `namespace` | string | `"default"` | The namespace to create the session in. Without it, Steel uses the project's namespace, which is `"default"` for a new project. It holds letters, digits, `_`, `.`, `:` and `-`, and it is not `.` or `..`. | [Projects and namespaces](https://steel.dev/docs/production/projects-and-namespaces) |
| `optimizeBandwidth` | boolean or object | None | Blocks resources so that the session uses less bandwidth. `true` blocks images, media and stylesheets. See [optimizeBandwidth](https://steel.dev/docs/sessions/configuration#optimizebandwidth). | [Reduce bandwidth](https://steel.dev/docs/sessions/bandwidth) |
| `projectId` | string (UUID) | The key's project. Required with an organization key. | The project to create the session in. A project key always uses its own project and ignores this option. | [Projects and namespaces](https://steel.dev/docs/production/projects-and-namespaces) |
| `timeout` | integer | `300000` (5 minutes) | The longest time that the session can run, in milliseconds. The minimum is 15000, and Steel raises a smaller value to 15000. The maximum is 15 minutes on Launch, 1 hour on Scale and up to 24 hours on Enterprise. | [Set timeouts](https://steel.dev/docs/sessions/timeouts) |
| `userAgent` | string | None | A custom user agent string for the browser. | [Fingerprints](https://steel.dev/docs/stealth/fingerprints) |

### deviceConfig

| Field | Type | Default | Description |
| - | - | - | - |
| `device` | `"desktop"` or `"mobile"` | `"desktop"` | `"mobile"` gives the session a mobile user agent, viewport, touch input and fingerprint. |

### dimensions

| Field | Type | Default | Description |
| - | - | - | - |
| `height` | integer | Required | The height in pixels. |
| `width` | integer | Required | The width in pixels. |

A mobile session needs at least 508 × 1074 (width × height). A request with smaller dimensions fails with `400`. A mobile session with no `dimensions` in the request or in its profile uses 508 × 1074.

### metadata

`metadata` is a flat object of your own keys and values. Steel returns it on every session response. It follows these rules:

- It holds at most 50 keys and 8192 bytes of UTF-8 JSON.
- A key starts with a letter, holds only letters, digits, `_`, `.` and `-`, and has at most 64 characters.
- Keys that start with `steel_` are reserved.
- A value is a string of at most 1024 characters, a finite number or a boolean. A string is valid Unicode with no NUL character.
- Steel stores numbers and booleans as strings, so `3` and `"3"` are the same value.

### optimizeBandwidth

Pass `true` to block images, media and stylesheets. Pass an object to choose what to block. The host and URL lists apply only in the object form.

| Field | Type | Description |
| - | - | - |
| `blockHosts` | string array | Blocks requests to these hosts. |
| `blockImages` | boolean | Blocks images. |
| `blockMedia` | boolean | Blocks media. |
| `blockStylesheets` | boolean | Blocks stylesheets. |
| `blockUrlPatterns` | string array | Blocks requests whose URL matches one of these patterns. |

## Stealth

| Option | Type | Default | What it does | Page |
| - | - | - | - | - |
| `caCertificates` | string array | None | Root CA certificates, in PEM format, that the session trusts. **Experimental.** | [Proxies](https://steel.dev/docs/stealth/proxies) |
| `proxyUrl` | string (URI) | None | Your own proxy server, as `http://username:password@hostname:port` or with `https://`. It overrides `useProxy`. | [Proxies](https://steel.dev/docs/stealth/proxies) |
| `solveCaptcha` | boolean | `false` | Turns on CAPTCHA solving. | [CAPTCHA solving](https://steel.dev/docs/stealth/captcha-solving) |
| `stealthConfig` | object | None | Settings for the fingerprint, mouse and key input, and CAPTCHA solving. See [stealthConfig](https://steel.dev/docs/sessions/configuration#stealthconfig). | [Fingerprints](https://steel.dev/docs/stealth/fingerprints) |
| `useProxy` | boolean or object | None | Routes the browser through a Steel proxy, a dedicated IP or your own proxy. See [useProxy](https://steel.dev/docs/sessions/configuration#useproxy). | [Proxies](https://steel.dev/docs/stealth/proxies) |

Steel proxies and CAPTCHA solving work on Scale and Enterprise, and on Launch after you [verify your account](https://steel.dev/docs/platform/pricing#verify-a-launch-account).

### stealthConfig

| Field | Type | Default | Description |
| - | - | - | - |
| `autoCaptchaSolving` | boolean | `true` | With `solveCaptcha`, Steel solves a CAPTCHA as soon as it detects one. Set it to `false` to detect CAPTCHAs only, and start each solve yourself with the [solve endpoints](https://steel.dev/docs/stealth/captcha-solving#solve-on-request). |
| `humanizeInteractions` | boolean | `false` | Makes the mouse and key input that you send over CDP act more like a person. The mouse moves along a curved path, and each key event waits a random 10 to 150 milliseconds. |
| `skipFingerprintInjection` | boolean | `false` | Skips the fingerprint that Steel generates for the session. Set it only when your code controls the fingerprint. |

### useProxy

| Value | What it does | Page |
| - | - | - |
| `true` | Routes the browser through a Steel residential proxy in the United States. | [Proxies](https://steel.dev/docs/stealth/proxies) |
| `false` | Uses no Steel proxy. | [Proxies](https://steel.dev/docs/stealth/proxies) |
| `{"geolocation": {...}}` | Routes the browser through a Steel proxy in the country, state or city that you choose. See [useProxy.geolocation](https://steel.dev/docs/sessions/configuration#useproxy-geolocation). | [Proxies](https://steel.dev/docs/stealth/proxies) |
| `{"server": "URL"}` | Routes the browser through your own proxy server, as `proxyUrl` does. | [Proxies](https://steel.dev/docs/stealth/proxies) |
| `{"type": "fixed"}` | Uses any active dedicated IP of your organization. | [Dedicated IPs](https://steel.dev/docs/stealth/dedicated-ips) |
| `{"type": "fixed", "id": "fixed:ID"}` | Uses one dedicated IP. The `id` is `fixed:` followed by 6 to 64 letters, digits, `_` or `-`. | [Dedicated IPs](https://steel.dev/docs/stealth/dedicated-ips) |

### useProxy.geolocation

| Field | Type | Default | Description |
| - | - | - | - |
| `city` | string | None | A city, from the [list of cities](https://steel.dev/docs/reference/proxy-locations#cities). |
| `country` | string | Required | A two-letter country code (ISO 3166-1 alpha-2), from the [list of countries](https://steel.dev/docs/reference/proxy-locations#countries). |
| `state` | string | None | A two-letter US state code, such as `NY`, from the [list of states](https://steel.dev/docs/reference/proxy-locations#states). Use it only with `"country": "US"`. |

Pass each value exactly as it appears in the [Countries](https://steel.dev/docs/reference/proxy-locations#countries), [States](https://steel.dev/docs/reference/proxy-locations#states) and [Cities](https://steel.dev/docs/reference/proxy-locations#cities) lists. Some city values hold a space, such as `HO_CHI MINH CITY`.

The list has no `NEW_YORK`, `LOS_ANGELES` or `LONDON`. Some large cities are listed by district instead, such as `BROOKLYN`, `QUEENS` and `THE_BRONX` in New York, and `HACKNEY` in London. For a city that is not in the list, pass only `country`. In the United States, you can also pass `state`.

## Logins and state

| Option | Type | Default | What it does | Page |
| - | - | - | - | - |
| `credentials` | object | None | Fills stored credentials into sign-in forms. With `{}`, the defaults below apply. Without the option, Steel fills no credentials. See [credentials](https://steel.dev/docs/sessions/configuration#credentials). | [Credentials](https://steel.dev/docs/logins/credentials) |
| `persistProfile` | boolean | `false` | Saves the browser state to a profile after you release the session. With `profileId`, it updates that profile. Without `profileId`, Steel creates a new profile and returns its `profileId`. Do not use it with `credentials`, as [Use credentials with a profile](https://steel.dev/docs/logins/credentials#use-credentials-with-a-profile) explains. | [Profiles](https://steel.dev/docs/logins/profiles) |
| `profileId` | string (UUID) | None | Starts the session from a saved profile. The profile must be `READY`. A request with a profile that is still `UPLOADING` fails with `409`. | [Profiles](https://steel.dev/docs/logins/profiles) |
| `sessionContext` | object | Empty | Cookies and web storage that the session starts with. With `profileId`, it replaces the profile's context. See [sessionContext](https://steel.dev/docs/sessions/configuration#sessioncontext). | [Session context](https://steel.dev/docs/logins/session-context) |

### credentials

| Field | Type | Default | Description |
| - | - | - | - |
| `autoSubmit` | boolean | `true` | Submits the form after Steel fills it. |
| `blurFields` | boolean | `true` | Blurs the username and password fields right after Steel fills them, and shows dots instead of their text, so that a vision model cannot read the values. Steel does not blur the one-time password field. |
| `credentialProvider` | string | `"steel"` | The provider that resolves credentials while the session runs. Only `"steel"` is supported. |
| `exactOrigin` | boolean | `true` | Ignored. Steel fills the same pages with either value. [Credentials](https://steel.dev/docs/logins/credentials#use-credentials-in-a-session) says which pages Steel fills. |
| `origins` | string array | None | An allowlist of credential origins to fill in this session. |

The credentials must be in the same project and namespace as the session.

### sessionContext

| Field | Type | Description |
| - | - | - |
| `cookies` | object array | Cookies to set in the session. See the cookie fields below. |
| `indexedDB` | object | IndexedDB databases to set, keyed by domain. Each value is an array of databases. |
| `localStorage` | object | localStorage items to set, keyed by domain. Each value maps keys to string values. |
| `sessionStorage` | object | sessionStorage items to set, keyed by domain. Each value maps keys to string values. |

#### Cookie fields

| Field | Type | Required | Description |
| - | - | - | - |
| `domain` | string | No | The domain that the cookie is sent to, such as `example.com`. |
| `expires` | number | No | When the cookie expires, in seconds since the Unix epoch. Without it, the cookie is a session cookie. |
| `httpOnly` | boolean | No | `true` hides the cookie from the page's JavaScript. |
| `name` | string | Yes | The cookie's name. |
| `partitionKey` | object | No | The partition of a partitioned cookie: `topLevelSite` (string, required) and `hasCrossSiteAncestor` (boolean, required). Without it, the cookie is not partitioned. |
| `path` | string | No | The URL path that the cookie applies to, such as `/`. |
| `priority` | string | No | `Low`, `Medium` or `High`. |
| `sameParty` | boolean | No | Read from the browser. You do not need to set it. |
| `sameSite` | string | No | `Strict`, `Lax` or `None`. |
| `secure` | boolean | No | `true` sends the cookie over HTTPS only. |
| `session` | boolean | No | Read from the browser: `true` for a cookie with no expiry. Ignored when you set a cookie. |
| `size` | number | No | Read from the browser: the cookie's size. Ignored when you set a cookie. |
| `sourcePort` | number | No | The port of the origin that set the cookie, from 1 to 65535, or `-1` for an unspecified port. |
| `sourceScheme` | string | No | The scheme of the origin that set the cookie: `Unset`, `NonSecure` or `Secure`. |
| `url` | string | No | The URL to set the cookie for. The browser takes the default `domain`, `path` and scheme from it. |
| `value` | string | Yes | The cookie's value. |

#### IndexedDB fields

Each database in `indexedDB` has an `id` (number), a `name` (string) and `data`, an array of object stores. All three are required.

| Object | Field | Type | Required |
| - | - | - | - |
| Object store | `id` | number | Yes |
| Object store | `name` | string | Yes |
| Object store | `records` | array of records | Yes |
| Record | `key` | any | Yes |
| Record | `value` | any | Yes |
| Record | `blobFiles` | array of blob files | No |
| Blob file | `blobNumber` | number | Yes |
| Blob file | `mimeType` | string | Yes |
| Blob file | `size` | number | Yes |
| Blob file | `filename` | string | No |
| Blob file | `lastModified` | string (date-time) | No |
| Blob file | `path` | string | No |

## Files and extensions

| Option | Type | Default | What it does | Page |
| - | - | - | - | - |
| `extensionIds` | string array | None | The IDs of the extensions to install in the session. `["all_ext"]` installs every extension that you uploaded. | [Extensions](https://steel.dev/docs/sessions/extensions) |

The create-session request has no option for files. Upload files to a running session with the [Files API](https://steel.dev/docs/sessions/files).

## Observability

| Option | Type | Default | What it does | Page |
| - | - | - | - | - |
| `debugConfig` | object | None | Settings for live view. See [debugConfig](https://steel.dev/docs/sessions/configuration#debugconfig). | [Live view](https://steel.dev/docs/observability/live-view) |
| `recording` | boolean | `true` | Records a headful session for playback after it ends. With `false`, live view still works. | [Recordings](https://steel.dev/docs/observability/recordings) |

### debugConfig

| Field | Type | Default | Description |
| - | - | - | - |
| `interactive` | boolean | `true` | Lets a person control the browser from live view. With `false`, live view is view-only. |
| `systemCursor` | boolean | `true` | Shows the operating system's cursor in the live view. It applies to headful sessions only. |
