Skip to content

Session configuration

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 →

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.

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

OptionTypeDefaultWhat it doesPage
blockAdsbooleantrueBlocks requests to known ad and tracking hosts. Set it to false to let them load.Reduce bandwidth
concurrencyintegerNoneIgnored. One request creates one session.Know your limits
deviceConfigobject{"device": "desktop"}Whether the browser presents itself as a desktop or a mobile device. See deviceConfig.Set the device and viewport
dimensionsobject1920 × 1080The 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.Set the device and viewport
experimentalFeaturesstring arrayNoneTurns on features by name. ["useStealthBrowser"] runs the session on Stealth Browser. The other names, which Steel does not publish, turn on Experimental features.Stealth Browser
fullscreenbooleanfalseHides 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
headlessbooleanfalseRuns the browser in headless mode. By default, the session is headful, with a visible browser window.Create a session
inactivityTimeoutintegerNoneReleases the session after this many milliseconds without activity, such as a CDP command or a Commands request. 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
metadataobject{}Your own key-value pairs for the session. See metadata.Add metadata
namespacestring"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
optimizeBandwidthboolean or objectNoneBlocks resources so that the session uses less bandwidth. true blocks images, media and stylesheets. See optimizeBandwidth.Reduce bandwidth
projectIdstring (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
timeoutinteger300000 (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
userAgentstringNoneA custom user agent string for the browser.Fingerprints

deviceConfig

FieldTypeDefaultDescription
device"desktop" or "mobile""desktop""mobile" gives the session a mobile user agent, viewport, touch input and fingerprint.

dimensions

FieldTypeDefaultDescription
heightintegerRequiredThe height in pixels.
widthintegerRequiredThe 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.

FieldTypeDescription
blockHostsstring arrayBlocks requests to these hosts.
blockImagesbooleanBlocks images.
blockMediabooleanBlocks media.
blockStylesheetsbooleanBlocks stylesheets.
blockUrlPatternsstring arrayBlocks requests whose URL matches one of these patterns.

Stealth

OptionTypeDefaultWhat it doesPage
caCertificatesstring arrayNoneRoot CA certificates, in PEM format, that the session trusts. Experimental.Proxies
proxyUrlstring (URI)NoneYour own proxy server, as http://username:password@hostname:port or with https://. It overrides useProxy.Proxies
solveCaptchabooleanfalseTurns on CAPTCHA solving.CAPTCHA solving
stealthConfigobjectNoneSettings for the fingerprint, mouse and key input, and CAPTCHA solving. See stealthConfig.Fingerprints
useProxyboolean or objectNoneRoutes the browser through a Steel proxy, a dedicated IP or your own proxy. See useProxy.Proxies

Steel proxies and CAPTCHA solving work on Scale and Enterprise, and on Launch after you verify your account.

stealthConfig

FieldTypeDefaultDescription
autoCaptchaSolvingbooleantrueWith 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.
humanizeInteractionsbooleanfalseMakes 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.
skipFingerprintInjectionbooleanfalseSkips the fingerprint that Steel generates for the session. Set it only when your code controls the fingerprint.

useProxy

ValueWhat it doesPage
trueRoutes the browser through a Steel residential proxy in the United States.Proxies
falseUses no Steel proxy.Proxies
{"geolocation": {...}}Routes the browser through a Steel proxy in the country, state or city that you choose. See useProxy.geolocation.Proxies
{"server": "URL"}Routes the browser through your own proxy server, as proxyUrl does.Proxies
{"type": "fixed"}Uses any active dedicated IP of your organization.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

useProxy.geolocation

FieldTypeDefaultDescription
citystringNoneA city, from the list of cities.
countrystringRequiredA two-letter country code (ISO 3166-1 alpha-2), from the list of countries.
statestringNoneA two-letter US state code, such as NY, from the list of states. Use it only with "country": "US".

Pass each value exactly as it appears in the Countries, States and 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

OptionTypeDefaultWhat it doesPage
credentialsobjectNoneFills stored credentials into sign-in forms. With {}, the defaults below apply. Without the option, Steel fills no credentials. See credentials.Credentials
persistProfilebooleanfalseSaves 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 explains.Profiles
profileIdstring (UUID)NoneStarts the session from a saved profile. The profile must be READY. A request with a profile that is still UPLOADING fails with 409.Profiles
sessionContextobjectEmptyCookies and web storage that the session starts with. With profileId, it replaces the profile's context. See sessionContext.Session context

credentials

FieldTypeDefaultDescription
autoSubmitbooleantrueSubmits the form after Steel fills it.
blurFieldsbooleantrueBlurs 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.
credentialProviderstring"steel"The provider that resolves credentials while the session runs. Only "steel" is supported.
exactOriginbooleantrueIgnored. Steel fills the same pages with either value. Credentials says which pages Steel fills.
originsstring arrayNoneAn allowlist of credential origins to fill in this session.

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

sessionContext

FieldTypeDescription
cookiesobject arrayCookies to set in the session. See the cookie fields below.
indexedDBobjectIndexedDB databases to set, keyed by domain. Each value is an array of databases.
localStorageobjectlocalStorage items to set, keyed by domain. Each value maps keys to string values.
sessionStorageobjectsessionStorage items to set, keyed by domain. Each value maps keys to string values.

Cookie fields

FieldTypeRequiredDescription
domainstringNoThe domain that the cookie is sent to, such as example.com.
expiresnumberNoWhen the cookie expires, in seconds since the Unix epoch. Without it, the cookie is a session cookie.
httpOnlybooleanNotrue hides the cookie from the page's JavaScript.
namestringYesThe cookie's name.
partitionKeyobjectNoThe partition of a partitioned cookie: topLevelSite (string, required) and hasCrossSiteAncestor (boolean, required). Without it, the cookie is not partitioned.
pathstringNoThe URL path that the cookie applies to, such as /.
prioritystringNoLow, Medium or High.
samePartybooleanNoRead from the browser. You do not need to set it.
sameSitestringNoStrict, Lax or None.
securebooleanNotrue sends the cookie over HTTPS only.
sessionbooleanNoRead from the browser: true for a cookie with no expiry. Ignored when you set a cookie.
sizenumberNoRead from the browser: the cookie's size. Ignored when you set a cookie.
sourcePortnumberNoThe port of the origin that set the cookie, from 1 to 65535, or -1 for an unspecified port.
sourceSchemestringNoThe scheme of the origin that set the cookie: Unset, NonSecure or Secure.
urlstringNoThe URL to set the cookie for. The browser takes the default domain, path and scheme from it.
valuestringYesThe 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.

ObjectFieldTypeRequired
Object storeidnumberYes
Object storenamestringYes
Object storerecordsarray of recordsYes
RecordkeyanyYes
RecordvalueanyYes
RecordblobFilesarray of blob filesNo
Blob fileblobNumbernumberYes
Blob filemimeTypestringYes
Blob filesizenumberYes
Blob filefilenamestringNo
Blob filelastModifiedstring (date-time)No
Blob filepathstringNo

Files and extensions

OptionTypeDefaultWhat it doesPage
extensionIdsstring arrayNoneThe IDs of the extensions to install in the session. ["all_ext"] installs every extension that you uploaded.Extensions

The create-session request has no option for files. Upload files to a running session with the Files API.

Observability

OptionTypeDefaultWhat it doesPage
debugConfigobjectNoneSettings for live view. See debugConfig.Live view
recordingbooleantrueRecords a headful session for playback after it ends. With false, live view still works.Recordings

debugConfig

FieldTypeDefaultDescription
interactivebooleantrueLets a person control the browser from live view. With false, live view is view-only.
systemCursorbooleantrueShows the operating system's cursor in the live view. It applies to headful sessions only.