` soup before the first sentence. Markdown collapses that to the text, the structure, and the links, so you spend tokens on content instead of tags. The wiring is small once you have the string: ```typescript const { content, metadata } = await client.scrape({ url: TARGET_URL, format: ["markdown"], }); const answer = await llm.chat({ messages: [ { role: "system", content: "Answer using only the page below." }, { role: "user", content: `# ${metadata.title}\n\n${content.markdown}` }, ], }); ``` That is the whole integration: scrape to Markdown, prepend the title, hand it to a model. No selectors, no `page.evaluate`, no waiting on a DOM you do not control. One failure mode to plan for: a heavily client-rendered page can return near-empty Markdown if the content paints after the initial load. When `content.markdown` comes back short for a site you know is rich, add `delay` (milliseconds) to the `scrape()` call so the page settles before capture. Check `metadata.statusCode` too. A scrape of a 403 or a soft-blocked page still succeeds at the HTTP level but hands you the block page's text, not the content you wanted. ## What you get back `format` is an array, so you can ask for more than one representation in a single call: `["markdown", "html", "cleaned_html", "readability"]`. Each lands under `content` on the response (`content.markdown`, `content.html`, and so on), and the field is undefined when you did not request that format, which is why the example reads `content.markdown ?? ""`. The response carries more than the body. `scraped.metadata` holds the page `title`, `description`, `statusCode`, Open Graph tags, and the canonical URL. `scraped.links` is a flat array of `{ text, url }` for every link on the page, handy when you want an LLM to pick a next page to visit. The example prints the status code, title, link count, and the first 500 characters of Markdown so you can see the shape without dumping a whole article to the terminal. `screenshot()` and `pdf()` differ from `scrape()` in one way worth knowing up front: they return a hosted URL, not bytes. `shot.url` and `pdf.url` point at the rendered artifact on Steel's storage, so the example logs the links rather than writing files. If you want the bytes on disk, fetch the URL yourself. The Python sibling does exactly that. ## Run it ```bash cd examples/scrape-ts cp .env.example .env # set STEEL_API_KEY npm install npm start ``` Get a key at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys). `TARGET_URL` in `.env` is optional and defaults to Hacker News. Your output varies. Structure looks like this: ```text Steel Scrape API (TypeScript) ============================================================ Scraping https://news.ycombinator.com to markdown... HTTP 200 | Hacker News Links found: 174 Markdown length: 6841 characters --- Markdown preview (first 500 chars) --- # Hacker News * [new](newest) * [past](front) * [comments](newcomments) * [ask](ask) * [show](show) ... --- end preview --- Capturing a full-page screenshot... Screenshot hosted at: https://steel-screenshots.s3.amazonaws.com/... Rendering the page to PDF... PDF hosted at: https://steel-screenshots.s3.amazonaws.com/... Done. Feed the markdown straight into an LLM prompt. ``` Each of the three calls is one billed request against Steel, so a full run costs a few cents of browser time. There is no session left open to leak: `scrape()`, `screenshot()`, and `pdf()` each return when the work is finished, so unlike the browser-driving recipes there is no `release()` to forget. ## Make it yours - **Pipe Markdown into a model.** Pass `markdown` as the user message to your LLM of choice and ask it to summarize the page or pull out structured fields. This is the whole reason to scrape to Markdown instead of HTML. - **Ask for several formats at once.** Set `format: ["markdown", "html"]` when you want the clean text for the model and the raw HTML for a fallback parser, both from a single request. - **Bundle artifacts into the scrape.** Instead of separate `screenshot()` and `pdf()` calls, pass `screenshot: true` and `pdf: true` to `scrape()`. The URLs come back on `scraped.screenshot` and `scraped.pdf`, which is one billed request instead of three. - **Get past anti-bot pages.** Add `useProxy: true` to route through Steel's residential proxies, or `delay: 3000` to wait for client-side rendering before the capture. - **Pick a region.** `region` accepts values like `"iad"` or `"fra"` to run the fetch closer to the target or to your users. ## Related [Python version](/cookbook/scrape) renders the same endpoints and writes the screenshot and PDF to disk as files. [Rust version](/cookbook/scrape) is the lowest-friction way into the Rust SDK. For a recipe that drives a real browser instead of the direct API, see [playwright-ts](/cookbook/playwright). Full method and parameter reference lives in the [steel-sdk package](https://www.npmjs.com/package/steel-sdk). **Python** Steel's `/v1/scrape` endpoint runs a browser server-side and hands back the rendered page. There is no session to create, no CDP socket to attach to, and no browser library on your machine. You call one method, and you get the page content, plus an optional screenshot and PDF. This recipe turns that single call into three files on disk: `page.md`, `screenshot.png`, and `page.pdf`. ```python result = client.scrape( url=TARGET_URL, format=["markdown"], screenshot=True, pdf=True, ) ``` The one detail worth internalizing: the response mixes inline data and hosted artifacts. `result.content.markdown` is a string you can write straight to a file. But `result.screenshot.url` and `result.pdf.url` are **hosted URLs**, not bytes. Steel renders the image and PDF, stores them, and returns links. So the recipe writes the markdown directly, then fetches the two URLs with `urllib` and saves the bytes. The `download` helper does the fetch; `main` wires the three writes. Because there is no session object, there is no teardown. `client.sessions.release(...)` does not apply here. You pay for the render, the response comes back, and you are done. That makes scrape the lowest-friction way to pull a page into an agent's context: one call, structured output, no lifecycle to manage. ## Run it ```bash cd examples/scrape-py cp .env.example .env # set STEEL_API_KEY uv run main.py ``` Grab a key at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys). `uv sync` runs automatically on first `uv run`, so there is no separate install step. Your output varies. Structure looks like this: ```text Steel Scrape API (Python) ============================================================ Scraping https://news.ycombinator.com ... Fetched "Hacker News" (HTTP 200) Markdown: 8421 chars, 147 links Saved page.md (8421 chars) Saved screenshot.png (184320 bytes) Saved page.pdf (96774 bytes) Artifacts written to /path/to/examples/scrape-py/output Done! ``` The three files land in `output/` next to `main.py`. Open `page.md` to see the markdown an LLM would read, `screenshot.png` for the rendered viewport, and `page.pdf` for a print-layout capture. A scrape costs a few cents of browser time. You are billed per render, not per minute, so a one-shot scrape is cheaper than spinning up a full session for the same page. If you only need text, drop `screenshot=True` and `pdf=True` and you skip the render-and-host work for the artifacts you are not using. ## Make it yours - **Change the target.** Set `TARGET_URL` in `.env`, or edit the default in `main.py`. Everything downstream is the same. - **Pick your formats.** `format` accepts any of `markdown`, `html`, `cleaned_html`, and `readability`. Pass a list to get several at once, then read them off `result.content` (`result.content.html`, `result.content.cleaned_html`, and so on). `cleaned_html` strips scripts and boilerplate; `readability` returns article-extracted structure. - **Mine the metadata.** `result.metadata` carries `title`, `description`, `status_code`, Open Graph fields (`og_title`, `og_image`), `canonical`, `author`, and `json_ld`. `result.links` is a list of `{text, url}` for every link on the page, which is a ready-made frontier for a crawler. - **Get the artifacts without the markdown.** `client.screenshot(url=..., full_page=True)` and `client.pdf(url=...)` are standalone calls that each return a single hosted URL. Use them when you want a capture and nothing else. `full_page=True` captures past the fold. - **Reach difficult sites.** Pass `use_proxy=True` to route the render through Steel's residential proxy network for pages that block datacenter traffic. ## How scrape differs from a browser session The other recipes in the cookbook connect a browser library (Playwright, Selenium) to a live Steel session over CDP, then drive clicks and reads themselves. That is the right tool when you need to log in, fill forms, or step through an app. Scrape is the right tool when you just want the page as it renders: one request in, content out, nothing to keep alive. If your agent's job is "read this URL," reach for scrape first and graduate to a session only when you need interaction. ## Related [TypeScript version](/cookbook/scrape) covers the same endpoint with the clean-markdown-for-LLM angle. [Rust version](/cookbook/scrape) walks the three calls separately. For a live, interactive browser instead, see [playwright-py](/cookbook/playwright). **Rust** Steel's REST API turns a URL into structured content without a browser on your side. The `steel-rs` crate wraps three of those endpoints as plain async methods: `client.scrape()` returns parsed content plus typed metadata, `client.screenshot()` and `client.pdf()` render the page and hand back a hosted file URL. There is no session to create, connect to, or release. Each call is one stateless request that runs a browser on Steel's side and returns when the page is done. That makes this the shortest path into Steel from Rust, and it leans on the SDK's typed structs rather than raw JSON. `scrape()` deserializes into a `ScrapeResponse`, so the fields are real Rust types you can pattern-match on: ```rust let scraped = client .scrape(ClientScrapeParams { url: TARGET_URL.to_string(), format: Some(vec![ScrapeRequestFormatItem::Markdown]), // remaining options set to None; see main.rs }) .await?; let meta = &scraped.metadata; // ScrapeResponseMetadata meta.status_code; // i64 meta.title.as_deref(); // Option<&str> meta.language.as_deref(); // Option<&str> scraped.links.len(); // Vec scraped.content.markdown; // Option ``` `metadata` carries about twenty parsed fields (Open Graph tags, canonical URL, author, published time, the HTTP status code), so you get the document's shape without writing a single selector. `content` holds whichever formats you asked for in `format`: `Markdown`, `HTML`, `CleanedHTML`, or `Readability`. Request only what you need; markdown alone keeps the payload small for LLM context. `main` runs all three calls against Hacker News, prints the typed metadata, and writes `page.md`, `screenshot.png`, and `page.pdf` to the working directory. Screenshot and PDF responses are a hosted URL, not bytes, so the `download` helper fetches each URL with `reqwest` and writes the file. The artifacts live on Steel for a while after the call, which is handy if you would rather hand the URL to another service than store the bytes yourself. ## Run it ```bash cd examples/scrape-rs cp .env.example .env # set STEEL_API_KEY cargo run ``` Get a key at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys). The first build pulls `steel-rs`, `tokio`, and `reqwest`, so it takes a moment; later runs are fast. Your output varies. Structure looks like this: ```text Scraping https://news.ycombinator.com ... status 200 title Hacker News language en links 183 markdown 14217 chars wrote page.md Capturing screenshot ... wrote screenshot.png Rendering PDF ... wrote page.pdf Done. ``` Three calls cost a few cents of browser time total. Steel bills per session-minute, and these one-shot endpoints spin up and tear down their own browser, so there is nothing to leak: no cleanup call, no session left running against the default 5-minute timeout. The trade-off is that each call is independent, so you cannot log in once and scrape five pages behind the auth. For that, open a session and drive a real browser (see Related). ## Make it yours - **Change the target.** Edit the `TARGET_URL` constant. Every call reads from it. - **Pick formats.** Pass more variants in `format`, for example `vec![ScrapeRequestFormatItem::Markdown, ScrapeRequestFormatItem::HTML]`, then read `scraped.content.html`. Each requested format comes back as its own `Option` field on `content`. - **Get the screenshot and PDF in one call.** `scrape()` takes `pdf: Some(true)` and `screenshot: Some(true)`; the URLs come back on `scraped.pdf` and `scraped.screenshot` instead of making three round trips. - **Handle anti-bot pages.** Set `use_proxy: Some(true)` on any of the params to route through a Steel residential proxy. Add `delay: Some(2000)` to wait for late-loading content before capture. - **Match on the status.** `meta.status_code` is an `i64`, so branch on it before trusting the content (a soft 404 still returns markdown). ## Related [TypeScript version](/cookbook/scrape) and [Python version](/cookbook/scrape) cover the same three endpoints. For a full browser session you connect to and drive over CDP, see [chromiumoxide](/cookbook/chromiumoxide). For the HTTP surface these methods wrap, see the [reqwest docs](https://docs.rs/reqwest) and [Tokio docs](https://tokio.rs). **Go** Steel's direct API turns a URL into clean content with no browser library and no session to manage. One `client.Scrape` call runs a browser server-side and returns the page as Markdown (or HTML, readability, or cleaned HTML) inline, while `client.Screenshot` and `client.Pdf` render the same page to hosted files. This recipe scrapes a page to Markdown, prints a preview, then captures a full-page screenshot and a PDF. It is the lowest-friction way to reach a page from Go: no CDP, no chromedp, no `defer release`. The scrape call leads: ```go scraped, err := client.Scrape(ctx, steel.ClientScrapeParams{ URL: targetURL, Format: &[]steel.ScrapeRequestFormatItem{steel.ScrapeRequestFormatItemMarkdown}, }) markdown := deref(scraped.Content.Markdown, "") title := deref(scraped.Metadata.Title, "(no title)") ``` Two Go specifics show up here. Optional request fields are pointers (`Format` is a `*[]ScrapeRequestFormatItem`, `FullPage` is a `*bool`), and steel-go ships no pointer constructors, so the recipe defines a one-line `ptr[T]` generic. Response fields like `Content.Markdown` and `Metadata.Title` are `*string`, so a small `deref` helper supplies a fallback. The format is a typed constant (`steel.ScrapeRequestFormatItemMarkdown`), not a bare string. Screenshot and PDF come back as hosted URLs, not bytes: ```go shot, _ := client.Screenshot(ctx, steel.ClientScreenshotParams{URL: targetURL, FullPage: ptr(true)}) fmt.Println(shot.URL) // https://... pdf, _ := client.Pdf(ctx, steel.ClientPdfParams{URL: targetURL}) fmt.Println(pdf.URL) ``` To keep the files, fetch each URL with `net/http` and write the bytes to disk. ## Run it ```bash cd examples/scrape-go cp .env.example .env # set STEEL_API_KEY go run . ``` Get a Steel key at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys). Point it at any page with `TARGET_URL` in `.env`. Your output varies. Structure looks like this: ```text Steel Scrape API (Go) ============================================================ Scraping https://news.ycombinator.com to markdown... HTTP 200 | Hacker News Links found: 184 Markdown length: 8423 characters --- Markdown preview (first 500 chars) --- [ clean Markdown for the page ] --- end preview --- Capturing a full-page screenshot... Screenshot hosted at: https://... Rendering the page to PDF... PDF hosted at: https://... Done. Feed the markdown straight into an LLM prompt. ``` A scrape call costs a few cents of browser time. Steel starts and tears down the browser per call, so there is no session to release. ## Make it yours - **Change the page.** Set `TARGET_URL` in `.env`, or pass a different URL to `client.Scrape`. - **Ask for several formats.** `Format` takes a slice, so request more than one at once (`ScrapeRequestFormatItemMarkdown`, `...HTML`, `...Readability`, `...CleanedHTML`). Each lands under its own field on `Content`. - **Save the artifacts.** Fetch `shot.URL` and `pdf.URL` with `net/http` and `os.WriteFile` to write `screenshot.png` and `page.pdf`, the way the Python recipe does. - **Scrape behind a proxy.** Set `UseProxy: ptr(true)` to route through a Steel residential proxy for geofenced or bot-sensitive pages. ## Related [scrape-ts](/cookbook/scrape) and [scrape-py](/cookbook/scrape) are the same direct API in TypeScript and Python, where the Python recipe writes the screenshot and PDF to disk. [scrape-rs](/cookbook/scrape) is the Rust version. For a full browser you drive yourself, [chromedp](/cookbook/chromedp) and [Rod](/cookbook/rod) connect over CDP instead. ## Related recipes - [Watch Claude pricing for divergent A/B variants](/cookbook/convex-price-watch): Convex cron plus two parallel Steel proxy probes against claude.com/pricing. Stores per-tier per-region snapshots and surfaces tiers where the probes disagree. - [Persist authenticated sessions with Profiles](/cookbook/profiles): Maintain authenticated sessions across Steel browser instances using profiles. - [Reuse authenticated sessions across browsers](/cookbook/auth-context): Maintain authenticated sessions across Steel browser instances by capturing and reusing cookies and local storage. # Automate a cloud browser with Selenium URL: https://docs.steel.dev/cookbook/selenium Selenium speaks the W3C WebDriver protocol over HTTP, not CDP. Every click, navigation, and `find_element` is an HTTP round-trip to a remote endpoint that implements the spec. Steel runs one at `http://connect.steelbrowser.com/selenium`, which is where `webdriver.Remote` points. The catch: Steel identifies callers with a `steel-api-key` header and routes each command to the right browser with a `session-id` header. `webdriver.Remote` doesn't expose a direct hook for custom headers, so the starter subclasses `RemoteConnection`: ```python class CustomRemoteConnection(RemoteConnection): _session_id = None def __init__(self, remote_server_addr: str, session_id: str): super().__init__(remote_server_addr) self._session_id = session_id def get_remote_connection_headers(self, parsed_url, keep_alive=False): headers = super().get_remote_connection_headers(parsed_url, keep_alive) headers.update({'steel-api-key': os.environ.get("STEEL_API_KEY")}) headers.update({'session-id': self._session_id}) return headers ``` `get_remote_connection_headers` runs on every outbound request. Selenium has no persistent connection to keep alive; the two headers ride along with each command. That's the integration. After the driver is wired, the rest is vanilla Selenium 4. One requirement: create the session with `is_selenium=True`. Steel provisions a WebDriver-compatible node for those sessions; without the flag you get a CDP browser that Selenium cannot drive. Steel's [Selenium integration](/integrations/selenium) covers the same setup on its own. ```python session = client.sessions.create(is_selenium=True) driver = webdriver.Remote( command_executor=CustomRemoteConnection( remote_server_addr='http://connect.steelbrowser.com/selenium', session_id=session.id, ), options=webdriver.ChromeOptions(), ) ``` From here, `driver.get(...)`, `WebDriverWait`, `By.CLASS_NAME`, and `find_elements` behave as they would against a local ChromeDriver. The scraping body inside `main()` uses `WebDriverWait` with `expected_conditions.presence_of_element_located` to block until Hacker News renders its story rows, then walks `athing` elements to pull title, link, and points. ## Run it ```bash cd examples/selenium cp .env.example .env # set STEEL_API_KEY uv run main.py ``` Grab a key at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys). The script prints a session viewer URL as it starts. Open it in another tab to watch the browser run live. Your output varies. Structure looks like this: ```text Creating Steel session... Session created successfully with Session ID: ab12cd34... You can view the session live at https://app.steel.dev/sessions/ab12cd34... Connected to browser via Selenium Navigating to Hacker News... Top 5 Hacker News Stories: 1. Claude 4.7 Opus released today Link: https://news.ycombinator.com/item?id=43218921 Points: 892 2. Show HN: A browser extension for reading on slow connections Link: https://github.com/user/project Points: 401 ... Releasing session... Session released Done! ``` A run costs a few cents of session time. Steel bills per session-minute, so `main()` wraps everything in a `try / finally` and calls `client.sessions.release(session.id)` on exit. Skip it and the browser idles until the default 5-minute timeout elapses. ## Make it yours - **Swap the target.** The scraping logic sits between the `Your Automations Go Here!` banner comments in `main.py`. Replace `driver.get(...)` and the `story_elements` loop with your own selectors; session setup and teardown stay put. - **Extend the session.** Pass `session_timeout=1800000` (30 minutes) alongside `is_selenium=True` in `sessions.create()` for longer runs. Keep `is_selenium=True`; it is the switch that provisions a WebDriver node. - **Wait on DOM state.** Each command is an HTTP round-trip, so blind `time.sleep` calls compound latency. Prefer `WebDriverWait` with `expected_conditions` (as in the example) to block on the specific element or state you need. - **Reuse the headers pattern.** `CustomRemoteConnection` is how you inject any extra header into every WebDriver request. The same subclass shape works for custom tracing or routing headers you want to attach per call. ## Related [Selenium Python docs](https://selenium-python.readthedocs.io) · [WebDriver protocol](https://w3c.github.io/webdriver/) ## Related recipes - [Run a Steel browser job with Trigger.dev](/cookbook/trigger-dev-browser-job): Queue a Trigger.dev task that creates a Steel session, drives Playwright over CDP, saves artifacts, and releases the browser in cleanup. - [Run a durable browser workflow with Temporal](/cookbook/temporal-browser-workflow): Build a Temporal TypeScript Workflow that schedules retryable Steel browser Activities to capture page summaries, screenshots, and Markdown artifacts. - [Automate a cloud browser with headless_chrome](/cookbook/headless-chrome): Use Steel with headless_chrome, the synchronous Rust equivalent of Puppeteer, to connect over CDP and scrape quotes with element handles. # Automate browsing with natural-language instructions using Stagehand URL: https://docs.steel.dev/cookbook/stagehand **TypeScript** Stagehand replaces brittle selectors with two LLM-backed primitives: - `stagehand.extract(instruction, schema)`: describe what you want, pass a Zod schema, get typed data back. - `stagehand.act(instruction)`: describe an action in natural language, Stagehand figures out the click / type / scroll. Both run against a Steel session over CDP, so Stagehand handles the reasoning and Steel handles the browser (stealth, proxies, live viewer). Steel's [Stagehand integration](/integrations/stagehand) covers the same wiring on its own. ```typescript stagehand = new Stagehand({ env: "LOCAL", localBrowserLaunchOptions: { cdpUrl: `${session.websocketUrl}&apiKey=${STEEL_API_KEY}`, }, model: { modelName: "openai/gpt-5", apiKey: OPENAI_API_KEY }, }); await stagehand.init(); ``` `env: "LOCAL"` tells Stagehand "I'll hand you the browser." That browser is Steel, reached via the CDP URL. `model` is the LLM that interprets every instruction. This starter targets **Stagehand v3**. Typed extraction, an instruction paired with a Zod schema: ```typescript const stories = await stagehand.extract( "extract the titles and ranks of the first 5 stories on the page", z.object({ stories: z.array(z.object({ title: z.string(), rank: z.number() })), }), ); ``` The schema isn't just documentation. Stagehand constrains the LLM's output against it and gives you a typed result at runtime. Swap the prompt and schema for any extraction problem: forms, tables, search results, prices. Natural-language action, no selector required: ```typescript await stagehand.act("click the 'new' link in the top navigation"); ``` Stagehand inspects the DOM, picks the matching element, and clicks it. ## Run it ```bash cd examples/stagehand-ts cp .env.example .env # set STEEL_API_KEY and OPENAI_API_KEY npm install npm start ``` Get keys from [app.steel.dev](https://app.steel.dev/settings/api-keys) and [platform.openai.com](https://platform.openai.com/api-keys). A session viewer URL prints as the script starts. Open it in another tab to watch Stagehand work. Your output varies. Structure looks like this: ```text Creating Steel session... Steel Session created! View session at https://app.steel.dev/sessions/ab12cd34… Initializing Stagehand... Connected to browser via Stagehand Navigating to Hacker News... Extracting top stories using AI... Top 5 Hacker News Stories: 1. Claude 4.7 Opus released today 2. Show HN: A browser extension for reading on slow connections 3. … Navigating to HN's 'new' section via a natural-language click... Navigated to new stories! Automation completed successfully! ``` A full run takes ~30 seconds and costs a few cents of Steel session time plus OpenAI tokens for each `extract` / `act` call. ## Make it yours - **Swap the schema and prompt.** `extract()` works on any data shape: forms, invoices, product grids, tables. Change the `stagehand.extract` call in `index.ts` to whatever you need to read off a page. - **Chain acts and extracts.** Break a task into natural-language steps: "sign in with these creds, then extract invoices from the past month." Each step is one `act()` or `extract()`. - **Try another model.** `gpt-5` works well out of the box; Claude and Gemini also work. Swap `modelName` and `apiKey` in the `Stagehand` config. ## Related [Python version](/cookbook/stagehand) · [Stagehand docs](https://docs.stagehand.dev) **Python** Stagehand v3 ships two LLM-backed primitives that replace CSS selectors with natural language: - `sessions.extract(instruction, schema)`: describe what you want, pass a JSON schema, get structured data back. - `sessions.act(instruction)`: describe an action, Stagehand decides whether to click, type, or scroll. Both run inside an embedded local Stagehand server that drives a Steel-hosted Chrome over CDP. ```python stagehand = AsyncStagehand( server="local", model_api_key=OPENAI_API_KEY, local_ready_timeout_s=30.0, ) stagehand_session = await stagehand.sessions.start( model_name="openai/gpt-5", browser={ "type": "local", "launchOptions": { "cdpUrl": f"{session.websocket_url}&apiKey={STEEL_API_KEY}", }, }, ) session_id = stagehand_session.data.session_id ``` The Python SDK is async-first. Every `extract`, `act`, and `navigate` call returns a coroutine, and this starter uses `asyncio.run(main())` as the entry point. Unlike the TypeScript SDK, the Python v3 SDK exposes extract and act as SSE streams. The starter wraps that pattern in `_stream_to_result`: ```python async def _stream_to_result(stream, label): result_payload = None async for event in stream: if event.type == "log": print(f"[{label}][log] {event.data.message}") continue status = event.data.status if status == "finished": result_payload = event.data.result elif status == "error": raise RuntimeError(f"{label} stream: {event.data.error or 'unknown'}") return result_payload ``` `sessions.extract` takes a JSON schema dict and returns data that conforms to it. No Zod, no pydantic required: ```python STORY_SCHEMA = { "type": "object", "properties": { "stories": { "type": "array", "items": { "type": "object", "properties": { "title": {"type": "string"}, "rank": {"type": "integer"}, }, "required": ["title", "rank"], }, } }, "required": ["stories"], } extract_stream = stagehand.sessions.extract( id=session_id, instruction="Extract the titles and ranks of the first 5 stories on the page", schema=STORY_SCHEMA, stream_response=True, x_stream_response="true", ) stories = await _stream_to_result(extract_stream, "extract") ``` `sessions.act` takes an instruction and no selector: ```python act_stream = stagehand.sessions.act( id=session_id, instruction="click the 'new' link in the top navigation", stream_response=True, x_stream_response="true", ) await _stream_to_result(act_stream, "act") ``` ## Run it ```bash cd examples/stagehand-py cp .env.example .env # set STEEL_API_KEY and OPENAI_API_KEY uv run main.py ``` Get keys from [app.steel.dev](https://app.steel.dev/settings/api-keys) and [platform.openai.com](https://platform.openai.com/api-keys). The script prints a session viewer URL as it starts. Your output varies. Structure looks like this: ```text Creating Steel session... Steel Session created! View session at https://app.steel.dev/sessions/ab12cd34… Initializing Stagehand... Connected to browser via Stagehand Navigating to Hacker News... Extracting top stories using AI... Top 5 Hacker News Stories: 1. Claude 4.7 Opus released today 2. Show HN: A browser extension for reading on slow connections 3. … Navigating to HN's 'new' section via a natural-language click... Navigated to new stories! Automation completed successfully! ``` A full run takes ~30 seconds. The `finally` block in `main()` calls `stagehand.sessions.end`, `stagehand.close()`, and `client.sessions.release()`. Keep all three. ## Make it yours - **Swap the schema and prompt.** `STORY_SCHEMA` and the `sessions.extract` instruction in `main.py` are the only parts tied to the Hacker News demo. - **Chain acts and extracts.** Break a task into natural-language steps, one `await _stream_to_result(...)` per step. - **Try another model.** `openai/gpt-5` is a reasonable default; Claude and Gemini also work. Change `model_name` on `sessions.start` and point `model_api_key` at the matching provider. - **Turn on Steel stealth.** Uncomment `use_proxy`, `solve_captcha`, or `session_timeout` in the `client.sessions.create()` call for sites with anti-bot. ## Related [TypeScript version](/cookbook/stagehand) · [Stagehand docs](https://docs.stagehand.dev) ## Related recipes - [Run a Steel browser job with Trigger.dev](/cookbook/trigger-dev-browser-job): Queue a Trigger.dev task that creates a Steel session, drives Playwright over CDP, saves artifacts, and releases the browser in cleanup. - [Run a durable browser workflow with Temporal](/cookbook/temporal-browser-workflow): Build a Temporal TypeScript Workflow that schedules retryable Steel browser Activities to capture page summaries, screenshots, and Markdown artifacts. - [Automate a cloud browser with headless_chrome](/cookbook/headless-chrome): Use Steel with headless_chrome, the synchronous Rust equivalent of Puppeteer, to connect over CDP and scrape quotes with element handles. # Build a research agent with Swiftide URL: https://docs.steel.dev/cookbook/swiftide [Swiftide](https://swiftide.rs) is a Rust framework for LLM applications: indexing pipelines, query pipelines, and agents that loop over tool calls until they reach an answer. This recipe builds an [agent](/cookbook/topics/agents) whose only tool reads the web through Steel's `scrape` endpoint, so the model works from clean Markdown instead of raw HTML and never touches a browser library or CDP. The agent runs on Anthropic (`claude-sonnet-4-6`) and the tool is a `#[derive(Tool)]` struct that owns the Steel client: ```rust #[derive(Clone, swiftide::Tool)] #[tool( description = "Fetch a web page through a Steel cloud browser and return it as clean \ Markdown along with the page's outbound links. Use this to read a URL.", param(name = "url", description = "Absolute URL of the page to read, including https://") )] struct ReadPage { client: Arc, } impl ReadPage { async fn read_page(&self, _ctx: &dyn AgentContext, url: &str) -> Result { let response = self.client.scrape(ClientScrapeParams { url: url.to_string(), format: Some(vec![ScrapeRequestFormatItem::Markdown]), .. }).await?; // ... return response.content.markdown plus response.links } } ``` The derive macro reads the struct's snake-case name (`ReadPage` -> `read_page`), finds the method with that name, and turns each `#[tool(param(...))]` into a JSON Schema field via `schemars`. Anything that implements `Tool` slots into `Agent::builder().tools(...)`, so a stateful struct and a `#[swiftide::tool]` free function are interchangeable at the call site. The struct form is what lets the tool hold `Arc`; a free function has nowhere to put it. Wiring the agent is four builder calls: ```rust let anthropic = Anthropic::builder().default_prompt_model("claude-sonnet-4-6").build()?; let mut agent = Agent::builder() .llm(&anthropic) .tools(vec![ReadPage { client: Arc::clone(&client) }]) .system_prompt(SYSTEM_PROMPT) .limit(8) .build()?; agent.query(TASK).await?; ``` `query` drives the loop: Claude reads the task, calls `read_page` on Hacker News, optionally follows one or two links the scrape returned, then calls the always-present `stop` tool when it has the answer. `.limit(8)` caps the round trips so a confused model can't loop forever. The `on_new_message` hook in `main` prints each assistant turn as it lands. ## Run it ```bash cd examples/swiftide cp .env.example .env # set STEEL_API_KEY and ANTHROPIC_API_KEY cargo run ``` Get a Steel key at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys) and an Anthropic key at [console.anthropic.com](https://console.anthropic.com/settings/keys). The Anthropic client reads `ANTHROPIC_API_KEY` from the environment on its own; the Steel key is passed to `Steel::new` explicitly. Your output varies. Structure looks like this: ```text Steel + Swiftide research agent ============================================================ read_page: https://news.ycombinator.com (18243 chars) The highest-scoring story on the front page is "Show HN: ..." with 642 points, submitted by pg. Let me open it to summarize. read_page: https://news.ycombinator.com/item?id=43218921 (9117 chars) Top story: "Show HN: ..." by pg, 642 points. It is a ... . The author built it to ... and the thread debates ... . Done. Steel scrape calls bill a little browser time; no session to release. ``` Each `scrape` call spins up a short-lived Steel browser server-side, so a run costs a few cents of browser time plus a few thousand Anthropic tokens. There is no long-lived session to release here: `scrape` opens and closes its own browser per call, which is the trade for not managing a session yourself. If you switch to `client.sessions().create(...)` for a persistent browser, you own the `release` call and Steel bills per session-minute until you make it. ## One thing that will bite you **The `#[derive(Tool)]` macro needs `serde` and `async-trait` as direct dependencies.** The expansion emits a bare `#[async_trait::async_trait]` and a `serde`-derived args struct without a `#[serde(crate = ...)]` override, so both crates have to resolve at the crate root even though you never name them. They are in `Cargo.toml` for that reason alone. The `#[swiftide::tool]` attribute macro on a free function fully qualifies its paths and does not need them, so that is the lighter option when your tool is stateless. Steel's request builders implement `IntoFuture` with a `Send` future, so `client.scrape(...).await` works directly inside a Swiftide tool even though tools run on a multi-threaded Tokio runtime. ## Make it yours - **Swap the task.** Change `TASK` and `SYSTEM_PROMPT` in `main.rs`. The tool stays the same; the agent re-plans against the new goal. - **Give it more reach.** The tool already returns up to 40 of the page's links, which is what lets the model follow a story into its comments. Raise `.limit(8)` if you want it to crawl deeper, and widen or drop the link cap. - **Add a second tool.** A `screenshot` tool backed by `client.screenshot(...)` (returns a base64 PNG) or a `pdf` tool backed by `client.pdf(...)` drops in as another `#[derive(Tool)]` struct in the `tools(vec![...])` list. The agent picks per turn. - **Change the model.** Any Anthropic chat model works in `default_prompt_model`. Swiftide also ships OpenAI, Gemini, Groq, and Ollama integrations behind feature flags; swap the `Anthropic` builder for one of those and the tools are unaffected. ## Related [Steel + rig (Rust)](/cookbook/rig) drives a real browser over CDP with chromiumoxide instead of the `scrape` endpoint. [Swiftide agent docs](https://swiftide.rs/agents/overview/) cover hooks, the `Tool` trait, and multi-agent setups. ## Related recipes - [Run a durable browser agent with Restate](/cookbook/restate-agent): Build a Restate Virtual Object in TypeScript that uses durable OpenAI planning steps and Steel scraping to answer browser research questions. - [Expose a Steel browser to any MCP client](/cookbook/mcp): Build a Model Context Protocol server in Go with the official SDK and chromedp that hands any MCP client a Steel cloud browser through explicit session-handle tools. - [Build a browser agent with Genkit](/cookbook/genkit): Use Steel with Genkit Go to build a tool-calling agent that navigates and extracts from a chromedp-backed browser and completes a web task. # Run a durable browser workflow with Temporal URL: https://docs.steel.dev/cookbook/temporal-browser-workflow **TypeScript** This recipe runs a [Temporal](/cookbook/topics/temporal) Workflow named `browserWorkflow`. The Workflow stays deterministic: it clamps small inputs, loops over URLs, and delegates each Steel scrape plus screenshot to the `capturePage` Activity. The Activity writes Markdown and PNG artifacts locally, then returns the compact page summary recorded in workflow history. The retry boundary lives on the Activity proxy in `workflows.ts`: ```ts const { capturePage } = proxyActivities({ startToCloseTimeout: "2 minutes", retry: { initialInterval: "5 seconds", maximumInterval: "30 seconds", backoffCoefficient: 2, maximumAttempts: 3, }, }); ``` If a page fetch fails, Temporal retries that Activity. If the worker restarts after one URL succeeds, the completed Activity result is replayed from history and the workflow resumes at the next URL. ## Run it Install the Temporal CLI if you do not already have it, then start a local dev server: ```bash temporal server start-dev ``` In another terminal, run the worker and workflow client: ```bash cd examples/temporal-browser-workflow-ts cp .env.example .env npm install npm start ``` Set `STEEL_API_KEY` in `.env`. Get a Steel key at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys). The Temporal dev server listens on `localhost:7233`, which matches `TEMPORAL_ADDRESS` in `.env.example`. Your output varies. Structure looks like this: ```json { "pages": [ { "url": "https://news.ycombinator.com/", "title": "Hacker News", "statusCode": 200, "screenshotUrl": "https://...", "artifacts": { "screenshotPath": "artifacts/news-ycombinator-com-2026-06-29T10-30-00-000Z.png", "markdownPath": "artifacts/news-ycombinator-com-2026-06-29T10-30-00-000Z.md" } } ], "pageCount": 2 } ``` Open the Temporal UI printed by `temporal server start-dev`. The workflow history shows one `capturePage` Activity per URL. ## Why Steel runs in an Activity Temporal Workflows replay, so they should not call Steel, `fetch`, `Date.now()`, the filesystem, or any other side-effecting API. `browserWorkflow` only decides which Activity to schedule next. `capturePage` owns the browser work and artifact writes: ```ts const scraped = await steel.scrape({ url, format: ["markdown"] }); const screenshot = await steel.screenshot({ url, fullPage }); await writeFile(markdownPath, toMarkdown(result, markdown), "utf8"); await download(screenshot.url, screenshotPath); ``` This keeps browser cost tied to Activity attempts. A failed Activity can retry. A completed Activity is not re-run during workflow replay. ## Make it yours - **Change the batch.** Set `TARGET_URLS` to a comma-separated list. The workflow caps each run at 10 URLs. - **Adjust extraction.** Use more fields from the Steel scrape response, or add PDF generation inside `capturePage`. - **Store artifacts durably.** Upload the PNG and Markdown files to object storage inside the Activity before returning. - **Deploy the worker.** Point `TEMPORAL_ADDRESS`, `TEMPORAL_NAMESPACE`, and `TEMPORAL_TASK_QUEUE` at your Temporal cluster, then run the same worker process. ## Related [temporal-browser-workflow-py](/cookbook/temporal-browser-workflow), [temporal-browser-workflow-go](/cookbook/temporal-browser-workflow), and [temporal-browser-workflow-rs](/cookbook/temporal-browser-workflow) implement the same workflow in other SDKs. See the [Temporal TypeScript SDK](https://docs.temporal.io/develop/typescript), [Steel scrape recipe](/cookbook/scrape), and [Trigger.dev browser job](/cookbook/trigger-dev-browser-job). **Python** `BrowserWorkflow` is a Python Temporal Workflow that batches page captures without putting network calls in replayed code. The workflow module contains only dataclasses and the deterministic loop. `main.py` registers `capture_page` as an Activity, and that Activity calls Steel, downloads the screenshot, and writes the Markdown report. The Python SDK's sandbox is the reason for the split. `workflows.py` does not import Steel or touch the filesystem. The worker imports both modules, registers the workflow and Activity, starts one workflow run, waits for the result, then shuts the local worker down. ## Run it Start a local Temporal dev server: ```bash temporal server start-dev ``` Run the Python worker and starter in another terminal: ```bash cd examples/temporal-browser-workflow-py cp .env.example .env python -m venv .venv source .venv/bin/activate pip install -e . python main.py ``` Set `STEEL_API_KEY` in `.env`. Get a Steel key at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys). Your output varies. Structure looks like this: ```text Started Temporal workflow: steel-browser-py-1782740000000 Workflow result: { "pages": [ { "url": "https://news.ycombinator.com", "title": "Hacker News", "status_code": 200, "screenshot_path": "artifacts/news.ycombinator.com-2026-06-29T10-30-00.png" } ], "page_count": 2 } ``` Artifacts land in `ARTIFACT_DIR`: ```text artifacts/ |-- news.ycombinator.com-2026-06-29T10-30-00.png `-- news.ycombinator.com-2026-06-29T10-30-00.md ``` ## Make it yours - **Change the batch.** Set `TARGET_URLS` to a comma-separated list. The workflow caps each run at 10 URLs. - **Return typed fields.** Add dataclass fields to `PageCapture`, then populate them inside `capture_page_sync`. - **Tighten failure policy.** Adjust `RetryPolicy` in `workflows.py` when a target site should stop retrying sooner. - **Move storage out of disk.** Replace `download` and `markdown_path.write_text` with object storage writes inside the Activity. ## Related [temporal-browser-workflow-ts](/cookbook/temporal-browser-workflow), [temporal-browser-workflow-go](/cookbook/temporal-browser-workflow), and [temporal-browser-workflow-rs](/cookbook/temporal-browser-workflow) cover the same shape in other SDKs. See the [Temporal Python SDK](https://docs.temporal.io/develop/python) and [Steel scrape recipe](/cookbook/scrape). **Rust** This recipe uses Temporal's prerelease Rust SDK (`temporalio-sdk` 0.4). `BrowserWorkflow` is declared with `#[workflow]` and keeps only deterministic control flow. `SteelActivities::capture_page` is declared with `#[activities]`, and that is where Steel, HTTP downloads, timestamps, and filesystem writes happen. The Rust SDK makes the workflow/activity boundary explicit: ```rust let page = ctx .start_activity( SteelActivities::capture_page, CapturePageInput { url, link_limit, full_page_screenshot }, activity_options.clone(), ) .await?; ``` The binary has two modes because the prerelease Rust worker is not `Send`; run the worker and starter as separate commands. ## Run it Start Temporal locally: ```bash temporal server start-dev ``` Run the Rust worker: ```bash cd examples/temporal-browser-workflow-rs cp .env.example .env cargo run -- worker ``` Start one workflow from another terminal: ```bash cd examples/temporal-browser-workflow-rs cargo run -- start ``` Set `STEEL_API_KEY` in `.env`. Get a Steel key at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys). The first build pulls Temporal Core, the Rust SDK macros, `steel-rs`, and their transitive dependencies. Your output varies. Structure looks like this: ```json { "pages": [ { "url": "https://news.ycombinator.com/", "title": "Hacker News", "statusCode": 200, "screenshotUrl": "https://...", "markdownPath": "artifacts/news-ycombinator-com-1782740000.md" } ], "pageCount": 2 } ``` ## Make it yours - **Keep the worker running.** `cargo run -- worker` already polls indefinitely. Put it under your process manager for a long-lived deployment. - **Tune retries.** Edit the `RetryPolicy` in `BrowserWorkflow::run`. - **Capture more artifacts.** Add PDF generation or object storage writes inside `capture_page_impl`. - **Watch SDK churn.** The Rust SDK is prerelease, so pin the `temporalio-*` crate versions before deploying. ## Related [temporal-browser-workflow-ts](/cookbook/temporal-browser-workflow), [temporal-browser-workflow-py](/cookbook/temporal-browser-workflow), and [temporal-browser-workflow-go](/cookbook/temporal-browser-workflow) cover the same workflow in stable SDKs. See the [Temporal Rust SDK crate](https://crates.io/crates/temporalio-sdk) and [Steel scrape recipe](/cookbook/scrape). **Go** This Go recipe keeps the Temporal pieces in one process for local runs. `main` connects to Temporal, starts a worker on `steel-browser-workflows-go`, registers `BrowserWorkflow` and `CapturePage`, then starts one workflow execution through the same SDK client. `BrowserWorkflow` is pure workflow code. It configures `workflow.ActivityOptions`, clamps the batch size, and calls `workflow.ExecuteActivity` once per URL. `CapturePage` is regular Go code: it calls Steel's scrape and screenshot APIs, writes artifacts, and returns a typed `PageCapture`. ## Run it Start Temporal locally: ```bash temporal server start-dev ``` Run the Go worker and starter: ```bash cd examples/temporal-browser-workflow-go cp .env.example .env go mod tidy go run . ``` Set `STEEL_API_KEY` in `.env`. Get a Steel key at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys). Your output varies. Structure looks like this: ```text Started Temporal workflow: steel-browser-go-1782740000000 Target URLs: https://news.ycombinator.com, https://example.com Workflow result: {Pages:[{URL:https://news.ycombinator.com/ Title:Hacker News ...}] PageCount:2} ``` The Temporal UI shows one Activity task for each URL, with the retry policy configured in `BrowserWorkflow`. ## Make it yours - **Change the batch.** Set `TARGET_URLS` to a comma-separated list. The workflow caps each run at 10 URLs. - **Keep the worker long-lived.** Remove `startWorkflow` from `main` when you want a worker process that only polls and executes tasks. - **Add more Steel calls.** Put PDF generation, profile-backed sessions, or proxy options inside `CapturePage`. - **Route artifacts elsewhere.** Replace `os.WriteFile` and `download` with S3, GCS, or your own blob store. ## Related [temporal-browser-workflow-ts](/cookbook/temporal-browser-workflow), [temporal-browser-workflow-py](/cookbook/temporal-browser-workflow), and [temporal-browser-workflow-rs](/cookbook/temporal-browser-workflow) cover the same workflow in other SDKs. See the [Temporal Go SDK](https://docs.temporal.io/develop/go) and [Steel scrape recipe](/cookbook/scrape). ## Related recipes - [Run a Steel browser job with Trigger.dev](/cookbook/trigger-dev-browser-job): Queue a Trigger.dev task that creates a Steel session, drives Playwright over CDP, saves artifacts, and releases the browser in cleanup. - [Automate a cloud browser with headless_chrome](/cookbook/headless-chrome): Use Steel with headless_chrome, the synchronous Rust equivalent of Puppeteer, to connect over CDP and scrape quotes with element handles. - [Automate a cloud browser with chromedp](/cookbook/chromedp): Use Steel with chromedp to connect over CDP, navigate to Hacker News, extract the top stories, and capture a screenshot. # Run a Steel browser job with Trigger.dev URL: https://docs.steel.dev/cookbook/trigger-dev-browser-job This recipe runs browser automation as a [queued background job](/cookbook/topics/triggerdev). The request path only enqueues `steel-browser-job`; the task creates a Steel session, connects Playwright over CDP, extracts a page summary, saves artifacts, and releases the session in `finally`. The core workflow lives in `src/trigger/browser-job.ts`: ```ts export const browserJob = task({ id: "steel-browser-job", maxDuration: 300, retry: { maxAttempts: 3 }, queue: { concurrencyLimit: 2 }, run: async (payload) => { session = await steel.sessions.create({ sessionTimeout: 600000 }); browser = await chromium.connectOverCDP( `${session.websocketUrl}&apiKey=${steelApiKey}` ); // browser work }, }); ``` `maxDuration` caps runaway jobs at 5 minutes. `retry` gives transient page or network failures another attempt. `queue.concurrencyLimit` keeps only two browser jobs active at once, so a burst of requests does not create an unbounded number of sessions. ## Run it ```bash cd examples/trigger-dev-browser-job cp .env.example .env npm install npm run dev ``` Set `STEEL_API_KEY`, `TRIGGER_SECRET_KEY`, and `TRIGGER_PROJECT_REF` in `.env`. Get a Steel key at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys). Use your Trigger.dev project ref from the Trigger.dev dashboard. In another terminal, enqueue one run: ```bash npm run trigger ``` The trigger script reads `TARGET_URL` and `LINK_LIMIT` from `.env`, calls `tasks.trigger("steel-browser-job", payload)`, and prints the run id. Watch the run in the Trigger.dev dashboard. Task output includes the Steel Live View URL, a hosted screenshot URL, local artifact paths, the extracted links, and duration in milliseconds. Local artifacts are written to `ARTIFACT_DIR`: ```text artifacts/ |-- browser-job-2026-06-29T10-30-00-000Z.png `-- browser-job-2026-06-29T10-30-00-000Z.md ``` ## Why the browser lives in the task Browser sessions are slow compared to HTTP handlers. A page can take 20-60 seconds when the site hydrates, retries, or challenges automation. Putting that work in a Trigger.dev task gives you a run record, logs, retries, a timeout, and queue backpressure. The API caller gets a run id immediately instead of waiting for the browser. The task still releases the Steel session on every path: ```ts finally { if (browser) await browser.close(); if (session) await steel.sessions.release(session.id); } ``` That cleanup is the cost control. If extraction throws after navigation, the remote browser still shuts down instead of idling until the session timeout. ## Make it yours - **Swap the extraction.** Replace the `page.evaluate` block with your site's selectors, form submission, or file download flow. - **Store artifacts durably.** Keep the hosted screenshot URL for public pages, or upload the `page.screenshot()` bytes to your own object storage when the artifact depends on logged-in session state. - **Tune concurrency.** Raise `queue.concurrencyLimit` for high-throughput crawls, or lower it when each job holds a logged-in profile. - **Add idempotency.** Pass an idempotency key from the caller when the same URL should not create duplicate browser runs. ## Related [Playwright recipe](/cookbook/playwright) | [Files recipe](/cookbook/files) | [Trigger.dev tasks](https://trigger.dev/docs/tasks/overview) ## Related recipes - [Run a durable browser workflow with Temporal](/cookbook/temporal-browser-workflow): Build a Temporal TypeScript Workflow that schedules retryable Steel browser Activities to capture page summaries, screenshots, and Markdown artifacts. - [Automate a cloud browser with headless_chrome](/cookbook/headless-chrome): Use Steel with headless_chrome, the synchronous Rust equivalent of Puppeteer, to connect over CDP and scrape quotes with element handles. - [Automate a cloud browser with chromedp](/cookbook/chromedp): Use Steel with chromedp to connect over CDP, navigate to Hacker News, extract the top stories, and capture a screenshot. # Stream a browser agent into a Next.js chat app URL: https://docs.steel.dev/cookbook/vercel-ai-sdk-nextjs A [Next.js](/cookbook/topics/nextjs) chat app where an [AI SDK v6](/integrations/ai-sdk) agent drives a Steel cloud browser server-side and streams every tool call back into the UI. `useChat` on the client posts to `/api/chat`; that route calls `streamText` with four Steel-backed tools (`openSession`, `navigate`, `snapshot`, `extract`). Each tool call surfaces as a typed `tool-*` part on the message stream, and a Live View iframe on the right lights up the moment the agent opens a session. ``` app/ ├── api/chat/route.ts # streamText + Steel tools, Node runtime ├── page.tsx # useChat, tool-call rendering, Live View iframe ├── layout.tsx # Geist fonts, dark theme └── globals.css ``` `app/api/chat/route.ts` pins `runtime = "nodejs"` (Playwright will not run on Edge) and `maxDuration = 120`. `next.config.mjs` lists `playwright`, `playwright-core`, and `steel-sdk` under `serverExternalPackages` so Next skips bundling them into the server build. The `POST` handler builds a per-request closure around three variables (`session`, `browser`, `page`) shared by every tool's `execute`, and `streamText` runs up to 15 steps (`stopWhen: stepCountIs(15)`). Both `onFinish` and `onAbort` call `cleanup()` to close the browser and `steel.sessions.release(session.id)`. A fifth tool, `submitForm`, carries `needsApproval: true`. Its body only runs if your approval UI confirms the call. It ships as a demo hook; wire it up when you add real destructive actions. ## Phase-gating with `prepareStep` Tool misuse by the model is a real failure mode. A second `openSession` mid-run would leak a browser; a `navigate` before any session exists throws. `prepareStep` constrains the active tool set per step: ```ts prepareStep: async ({ stepNumber, steps }) => { const sessionOpened = steps.some((s) => s.toolCalls?.some((tc) => tc.toolName === "openSession") ); if (stepNumber === 0 || !sessionOpened) { return { activeTools: ["openSession"] }; } return { activeTools: ["navigate", "snapshot", "extract", "submitForm"] }; }, ``` ## Run it ```bash cd examples/vercel-ai-sdk-nextjs cp .env.example .env # set STEEL_API_KEY and ANTHROPIC_API_KEY npm install npx playwright install chromium npm run dev ``` Get keys at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys) and [console.anthropic.com](https://console.anthropic.com/). Open [http://localhost:3000](http://localhost:3000) and try one of the seeded prompts: > Go to https://github.com/trending/python and tell me the top 3 AI/ML repos. A typical run takes ~20 seconds: `openSession` (~3s), `navigate` (~2s), `snapshot` (~1s), `extract` (~1s), then the model writes its reply. Server console logs each step: ```text step: openSession | 412 tokens step: navigate | 1083 tokens step: snapshot | 2847 tokens step: extract | 3104 tokens step: (text) | 3298 tokens ``` ## Deploying to Vercel Push to GitHub, import into Vercel, add `STEEL_API_KEY` and `ANTHROPIC_API_KEY` as environment variables. Playwright's Chromium has to be downloaded during the build, so set the Build Command to: ``` npx playwright install chromium && next build ``` The `/api/chat` route already declares `maxDuration = 120` and `runtime = "nodejs"`. ## Make it yours - **Change the model.** Swap `anthropic("claude-haiku-4-5")` for any model in `@ai-sdk/*`. The Zod tool schemas stay the same. - **Add a screenshot tool.** `await page.screenshot({ type: "png" })` returns a Buffer; return it base64-encoded and render it as an `` in the tool-call panel. - **Stream a plan step.** Add a `plan` tool with no side effects and a string input. The model can narrate its intent before executing. - **Turn on stealth.** Pass `useProxy`, `solveCaptcha`, or `sessionTimeout` options to `steel.sessions.create()` inside `openSession`. - **Wire the approval UI.** `needsApproval: true` on `submitForm` pauses execution and surfaces the call as a `tool-submitForm` part in `state: "input-available"`. Render an Approve/Reject pair and call `addToolResult` from `@ai-sdk/react` to resume. ## Related [Plain TS version](/cookbook/vercel-ai-sdk) · [AI SDK agents](https://ai-sdk.dev/docs/agents/overview) · [Loop control](https://ai-sdk.dev/docs/agents/loop-control) · [Next.js App Router](https://nextjs.org/docs/app) ## Related recipes - [Build a browser agent with Google ADK](/cookbook/google-adk): Use Steel with Google's Agent Development Kit (ADK) for Go to build a tool-using browser agent that drives a chromedp session over CDP and reads Hacker News. - [Build a typed browser agent with Pydantic AI](/cookbook/pydantic-ai): Use Steel with Pydantic AI to build typed, provider-agnostic browser agents with dependency injection. - [Build a typed browser agent with LangGraph](/cookbook/langgraph): Use Steel with LangGraph to build a typed browser agent with an explicit state-machine loop and a structured-output formatter node. # Build a typed browser agent with the Vercel AI SDK URL: https://docs.steel.dev/cookbook/vercel-ai-sdk The [Vercel AI SDK v6](https://ai-sdk.dev/docs/agents/overview) ships `ToolLoopAgent`, a [typed agent](/cookbook/topics/typed-output) that picks a tool, calls it, observes the result, and decides the next step. Give it tools that drive a Playwright page connected to a Steel session and you get a terminal browser agent with no UI scaffolding in the way. Steel's [AI SDK integration](/integrations/ai-sdk) covers the same pairing on its own. ```typescript const researchAgent = new ToolLoopAgent({ model: anthropic("claude-haiku-4-5"), instructions: "You operate a Steel cloud browser via tools...", stopWhen: [stepCountIs(15), hasToolCall("reportFindings")], tools: { openSession, navigate, snapshot, extract, reportFindings }, onStepFinish: async ({ stepNumber, toolCalls, usage }) => { ... }, }); const result = await researchAgent.generate({ prompt: "..." }); ``` `reportFindings` is the terminator. Its `inputSchema` is a Zod object (a `summary` string and an array of repo records) and it has **no `execute`**. In AI SDK v6, a tool with no `execute` stops the loop the moment the model calls it, and the call's `input` is your final typed answer. This sidesteps the Anthropic-on-tools issue where forcing JSON response format disables tool calling. ## Run it ```bash cd examples/vercel-ai-sdk-ts cp .env.example .env # set STEEL_API_KEY and ANTHROPIC_API_KEY npm install npm start ``` Get keys at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys) and [console.anthropic.com](https://console.anthropic.com/). The demo task is wired into `main()`: find the top 3 AI/ML repos on `github.com/trending/python?since=daily` and return name, URL, stars, and description. Your output varies. Structure looks like this: ```text Steel + AI SDK v6 (ToolLoopAgent) Starter ============================================================ openSession: session=842ms cdp=411ms step 1: openSession | 1183 tokens navigate: 1621ms step 2: navigate | 1402 tokens snapshot: 124ms (3892 chars, 48 links) step 3: snapshot | 5104 tokens extract: 98ms (10 rows) step 4: extract | 2881 tokens step 5: reportFindings | 3150 tokens Agent finished. Structured output: { "summary": "The top trending Python repos today center on...", "repos": [ { "name": "owner/repo", "url": "...", "stars": "1,204", "description": "..." }, ... ] } Releasing Steel session... Session released. Replay: https://app.steel.dev/sessions/ab12cd34... ``` A full run takes ~20 seconds and costs a few cents of Steel session time plus a small number of Anthropic tokens. The `finally` block in `main` calls `steel.sessions.release()`. ## Make it yours - **Swap the task.** Change the `prompt` in `main()` and the `reportFindings` schema. Everything else is task-agnostic. - **Swap the model.** `claude-haiku-4-5` is the default. For harder tasks, try `anthropic("claude-sonnet-4-6")`, `openai("gpt-5")`, or `google("gemini-2.5-pro")`. You can also use the [AI Gateway](https://vercel.com/docs/ai-gateway) string form, like `"anthropic/claude-haiku-4-5"`, to route through Vercel. - **Add tools.** A `click` tool wrapping `page.click`, a `fill` tool over `page.fill`, a `screenshot` tool that returns a base64 PNG for vision models. - **Phase-gate steps.** Use `prepareStep` to restrict which tools are callable on a given step. See the AI SDK's [loop control](https://ai-sdk.dev/docs/agents/loop-control) page. - **Turn on stealth.** Pass `useProxy`, `solveCaptcha`, or `sessionTimeout` to `steel.sessions.create({...})` inside `openSession` for sites with anti-bot. ## Related [Next.js version](/cookbook/vercel-ai-sdk-nextjs) · [AI SDK agents docs](https://ai-sdk.dev/docs/agents/overview) · [ToolLoopAgent reference](https://ai-sdk.dev/docs/agents/building-agents) ## Related recipes - [Build a browser agent with Google ADK](/cookbook/google-adk): Use Steel with Google's Agent Development Kit (ADK) for Go to build a tool-using browser agent that drives a chromedp session over CDP and reads Hacker News. - [Build a typed browser agent with Pydantic AI](/cookbook/pydantic-ai): Use Steel with Pydantic AI to build typed, provider-agnostic browser agents with dependency injection. - [Build a typed browser agent with LangGraph](/cookbook/langgraph): Use Steel with LangGraph to build a typed browser agent with an explicit state-machine loop and a structured-output formatter node. # Combine You.com search with Steel browser actions URL: https://docs.steel.dev/cookbook/you-com-search A [search-then-act agent](/cookbook/topics/search): [You.com](https://you.com/) handles discovery and static extraction, Steel handles real browser actions. The agent gets five tools across two cost tiers and is told to prefer the cheap tier. The Steel session is opened lazily on the first `navigate` call, so a question that resolves on search alone never spins up a browser. ```python tools = [youcom_search, youcom_contents, navigate, snapshot, click_text] SYSTEM = ( "You answer research-style questions by combining You.com APIs with a " "Steel cloud browser. Prefer the cheap path first: youcom_search to find " "candidate URLs, then youcom_contents to read them. Only call navigate, " "snapshot, or click_text when the page is JS-rendered, login-walled, or " "you need to interact (filters, toggles, form fields). ..." ) ``` You.com Search returns LLM-shaped JSON for any web query (`$5/1k calls`). You.com Contents fetches up to ten URLs of clean Markdown in one round trip (`$1/1k pages`). Both run in milliseconds against a CDN. Steel's cloud browser is the slow, expensive option you reach for when the page needs a real Chromium: a click, a form submit, a JS-rendered table, an auth wall the Contents API can't see through. Routing the agent through this hierarchy keeps token spend, latency, and session billing low on the questions that don't need a browser. ## The two tiers `youcom_search` and `youcom_contents` are plain `httpx` calls to `ydc-index.io/v1`. No SDK, no session lifecycle. Each tool prints its latency so you can see the cost gap. ```python @tool async def youcom_contents(urls: list[str]) -> dict: """Fetch clean Markdown for up to ~10 URLs in one call. Cheap, no browser, no JS rendering. Call this AFTER youcom_search to read static pages. If a page needs JS (login walls, dynamic data, interaction), escalate to navigate + snapshot. """ async with httpx.AsyncClient(timeout=60) as client: r = await client.post( f"{YOU_BASE}/contents", json={"urls": urls, "formats": ["markdown"]}, headers={"X-API-Key": YOUCOM_API_KEY, ...}, ) ... ``` The browser tools (`navigate`, `snapshot`, `click_text`) all funnel through `_ensure_session`, which creates the Steel session on demand and reuses it across calls. If the agent never escalates, `_session` stays `None` and the `finally` block prints "No Steel session was opened (cheap path only)." ```python async def _ensure_session() -> Page: global _session, _browser, _page, _playwright if _page is not None: return _page _session = steel.sessions.create() _playwright = await async_playwright().start() _browser = await _playwright.chromium.connect_over_cdp( f"{_session.websocket_url}&apiKey={STEEL_API_KEY}" ) ... return _page ``` ## What the agent escalates for `youcom_contents` returns the markdown a server would serve to a curl request. That covers most blog posts, docs sites, GitHub READMEs, news articles, and SEO-friendly product pages. It misses anything client-rendered: dashboards, SPAs without server fallbacks, paywalled content, in-page filters and toggles, anything behind a login. `snapshot` reads `document.body.innerText` from the live DOM after the page settles, so it sees JS-rendered text the Contents API cannot. `click_text` is a thin wrapper over Playwright's `get_by_text(...).first.click(...)` for buttons, tabs, and filters whose effect You.com cannot replay. The agent decides when the gap matters: the docstrings make the routing explicit, the system prompt reinforces it. The result is a graceful fall-through. Cheap question (a fact you can cite from a static page): one search, one contents, done in a few seconds for a fraction of a cent. Expensive question (something behind a click): the agent escalates exactly as far as it needs to and releases the session at the end. ## The agent loop `create_tool_calling_agent` builds a tool-calling prompt from the schemas LangChain extracts from each `@tool`'s signature and docstring. `AgentExecutor` runs the loop: model picks tools, executes them, feeds results back, stops when the model emits a text-only response. ```python agent = create_tool_calling_agent(model, tools, prompt) executor = AgentExecutor(agent=agent, tools=tools, max_iterations=10, verbose=False) result = await executor.ainvoke({"input": question}) ``` `max_iterations=10` is a safety net for runaway loops. `verbose=False` keeps the output clean; the per-tool latency lines from each tool give enough trace to follow the flow. For a richer trace, flip `verbose=True` or set `LANGSMITH_API_KEY` and `LANGSMITH_TRACING=true` in `.env`. ## Run it ```bash cd examples/you-com-search cp .env.example .env # set STEEL_API_KEY, ANTHROPIC_API_KEY, YOUCOM_API_KEY uv sync uv run playwright install chromium uv run main.py ``` Get keys at [app.steel.dev/settings/api-keys](https://app.steel.dev/settings/api-keys), [console.anthropic.com](https://console.anthropic.com/), and [you.com/platform](https://you.com/platform). New You.com accounts get $100 in credits with no card. Your output varies. The shape is illustrative, not literal: ```text Steel + You.com Search-Act Starter ============================================================ youcom_search: ( results) youcom_contents: ( pages) open_session: (live view: https://app.steel.dev/sessions/...) navigate: snapshot: ( chars, links) Agent finished. Releasing Steel session... Session released. Replay: https://app.steel.dev/sessions/... ``` If the agent answers from search and contents alone, the `open_session`, `navigate`, and `snapshot` lines (and the release line) won't appear; the run ends with `No Steel session was opened (cheap path only).` instead. You.com bills per call (search and contents are cheap); Steel bills per session minute, which is why the lazy-open matters. ## Make it yours - **Swap the cheap tool.** Replace `youcom_search` with the Research API (`https://api.you.com/v1/research`) when you want a multi-step reasoned answer instead of raw results. The agent gets fewer URLs but better-synthesized inputs. - **Add more browser actions.** `click_text` is the minimum interactive primitive. Add `fill(selector, text)`, `press(key)`, `wait_for_selector`, or `scroll` when the agent needs to operate forms or trigger lazy-loaded content. - **Tighten the routing.** The `verbose=False` agent re-derives the routing each turn. For repeatable production flows, replace the agent with an explicit two-step pipeline: always run `youcom_search`, always run `youcom_contents` on the top hit, only call browser tools if a heuristic flag (response too short, contains "Please enable JavaScript", etc.) trips. - **Trace with LangSmith.** Set `LANGSMITH_API_KEY` and `LANGSMITH_TRACING=true` in `.env`. No code changes; every tool call shows up at [smith.langchain.com](https://smith.langchain.com). - **Swap the model.** `ChatOpenAI(model="gpt-5-mini")` works without touching the tools. The system prompt is generic. - **Self-host.** Both Steel (open-source browser infra) and the cookbook are deployable; the You.com APIs are remote. For a fully self-hostable variant, replace `youcom_contents` with a local extractor (Trafilatura, Readability) and a search frontend like SearXNG, and keep Steel for the browser tier. ## Related [CrewAI](/cookbook/crewai) for a multi-agent research-and-report flow that uses Steel's `scrape` API instead of search. [LangGraph](/cookbook/langgraph) for an explicit state-machine version of the same browser loop. [You.com API docs](https://you.com/docs). ## Related recipes - [Run a durable browser agent with Restate](/cookbook/restate-agent): Build a Restate Virtual Object in TypeScript that uses durable OpenAI planning steps and Steel scraping to answer browser research questions. - [Expose a Steel browser to any MCP client](/cookbook/mcp): Build a Model Context Protocol server in Go with the official SDK and chromedp that hands any MCP client a Steel cloud browser through explicit session-handle tools. - [Build a browser agent with Genkit](/cookbook/genkit): Use Steel with Genkit Go to build a tool-calling agent that navigates and extracts from a chromedp-backed browser and completes a web task. # AgentKit URL: https://docs.steel.dev/integrations/agentkit AgentKit is Inngest's TypeScript framework for [building agent networks](/cookbook/topics/agents): single agents or coordinated teams that share state and route work through code or model-driven routers. The Steel integration runs each agent's browser actions on a Steel cloud session, so AgentKit handles the orchestration and Steel handles the browser. You can also expose MCP servers as tools and stream tokens and tool steps to a UI as the agent runs. ### Requirements * **Steel API Key**: Active Steel subscription * **Node.js**: v20+ * **Packages**: `@inngest/agent-kit`, `inngest` * **Model provider key**: OpenAI, Anthropic, Google Gemini, or any OpenAI-compatible endpoint ### Connect Steel to AgentKit Inside an AgentKit tool handler, create a Steel session and hand a Playwright `page` to your agent: ```typescript import { chromium } from "playwright"; import Steel from "steel-sdk"; const steel = new Steel({ steelAPIKey: process.env.STEEL_API_KEY! }); const session = await steel.sessions.create({}); const browser = await chromium.connectOverCDP( `${session.websocketUrl}&apiKey=${process.env.STEEL_API_KEY}`, ); const page = browser.contexts()[0].pages()[0]; // `page` is your Steel browser. Call it from AgentKit tool handlers ``` Full runnable starter: [Steel + AgentKit recipe →](/cookbook/agentkit) ### FAQ ### Do I need to change my existing AgentKit code to use Steel? No — AgentKit keeps handling orchestration, routing, and shared state. Inside a tool handler you create a Steel session, connect Playwright over CDP, and call the resulting `page` from your handlers. ### How do I connect AgentKit to a Steel browser session? Call `steel.sessions.create()`, connect with `chromium.connectOverCDP()` using the session's `websocketUrl` plus your `apiKey`, and take the first page of `browser.contexts()[0]` as the page your AgentKit tool handlers drive. ### Does AgentKit work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — pass them to `sessions.create()` (e.g. `useProxy`, `solveCaptcha`, `stealthConfig`). They're Steel-side session options, so your agent network and routers don't change. ### Resources * [AgentKit documentation](https://agentkit.inngest.com/overview) – Official documentation for AgentKit * [Examples gallery](https://agentkit.inngest.com/examples/overview) – Starter projects (support agent, SWE-bench, coding agent, web search) * [LLMs docs bundle](https://agentkit.inngest.com/llms-full.txt) – Markdown doc set for IDEs/LLMs * [Inngest Dev Server](https://agentkit.inngest.com/getting-started/local-development) – Live traces and I/O logs * [Steel Sessions API reference](/api-reference) – Programmatic session control * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Agno URL: https://docs.steel.dev/integrations/agno Agno is a Python framework for building [multi-agent systems](/cookbook/topics/agents) with shared memory, knowledge, and reasoning. The Steel integration wraps a Steel browser as an Agno toolkit, so Agno agents can navigate, fill forms, extract data, and combine browsing with retrieval-augmented reasoning. Agno is model-agnostic and natively multi-modal, which pairs well with Steel's reliable, sandboxed cloud browsers. ### Requirements * **Steel API Key**: Active Steel subscription * **Model provider key**: OpenAI, Anthropic, or any Agno-supported provider * **Python**: 3.10+ ### Connect Steel to Agno Wrap a Steel-backed Playwright `page` in an Agno `Toolkit`: ```python import os from playwright.sync_api import sync_playwright from steel import Steel steel = Steel(steel_api_key=os.environ["STEEL_API_KEY"]) session = steel.sessions.create() playwright = sync_playwright().start() browser = playwright.chromium.connect_over_cdp( f"{session.websocket_url}&apiKey={os.environ['STEEL_API_KEY']}" ) page = browser.contexts[0].pages[0] # `page` is your Steel browser. Wrap it in an Agno Toolkit ``` Full runnable starter: [Steel + Agno recipe →](/cookbook/agno) ### FAQ ### Do I need to change my existing Agno code to use Steel? No — Steel is exposed to Agno as a regular `Toolkit`. You connect Playwright to a Steel session over CDP and wrap the resulting `page` in the toolkit; agents, teams, memory, and reasoning stay as they were. ### How do I connect Agno to a Steel browser session? Create a session with `steel.sessions.create()`, connect with `playwright.chromium.connect_over_cdp(f"{session.websocket_url}&apiKey={STEEL_API_KEY}")`, take `browser.contexts[0].pages[0]` as your page, and wrap it in an Agno `Toolkit`. ### Does Agno work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — set them at session creation (e.g. `use_proxy`, `solve_captcha`, `stealth_config` on `sessions.create()`). Agno only sees the Playwright page, so these options don't touch your agent code. ### Which model providers can I use with Agno on Steel? Any Agno-supported provider — Agno is model-agnostic and natively multi-modal, so OpenAI, Anthropic, or others all work. You just need the provider key plus your Steel API key. ### Resources * [Agno documentation](https://docs.agno.com/) – Concepts, APIs, and examples for agents, teams, memory, and reasoning * [Steel Sessions API reference](/api-reference) – Manage Steel browser sessions programmatically * [Steel Discord](https://discord.gg/steel-dev) – Get help, share recipes, and discuss best practices # Browser Tool for the Vercel AI SDK URL: https://docs.steel.dev/integrations/ai-sdk The Vercel AI SDK is a TypeScript toolkit for building AI applications with typed tools, streaming, and a unified provider model. The Steel integration runs each tool against a Steel cloud session (open, navigate, snapshot, extract, return typed results), so you can stand up a [typed browser agent](/cookbook/topics/agents) in a few hundred lines. Pair the agent with a Next.js chat UI and embed Steel's Live View iframe alongside the chat to watch the browser as the agent runs. ### Requirements * **Steel API Key**: Active Steel subscription * **Node.js**: v20+ * **Packages**: `ai`, a provider package (e.g., `@ai-sdk/anthropic`), `steel-sdk`, `playwright`, `zod` * **Model provider key**: Anthropic, OpenAI, or any AI SDK-supported provider ### Connect Steel to the Vercel AI SDK Open a Steel session inside a typed AI SDK `tool()`: ```typescript import { tool } from "ai"; import { chromium } from "playwright"; import Steel from "steel-sdk"; import { z } from "zod"; const steel = new Steel({ steelAPIKey: process.env.STEEL_API_KEY! }); const openSession = tool({ description: "Open a Steel cloud browser session.", inputSchema: z.object({}), execute: async () => { const session = await steel.sessions.create({}); const browser = await chromium.connectOverCDP( `${session.websocketUrl}&apiKey=${process.env.STEEL_API_KEY}`, ); return { sessionId: session.id, liveViewUrl: session.sessionViewerUrl }; }, }); ``` Full runnable starters: * Server-only typed agent: [Steel + Vercel AI SDK recipe →](/cookbook/vercel-ai-sdk) * Next.js chat UI with embedded Steel Live View: [Steel + Vercel AI SDK + Next.js recipe →](/cookbook/vercel-ai-sdk-nextjs) ### FAQ ### Do I need to change my existing Vercel AI SDK code to use Steel? No — Steel slots in as a typed `tool()` from the `ai` package. The tool's `execute` opens a Steel session and connects Playwright over CDP; your streaming, provider setup, and the rest of the agent stay the same. ### How do I connect the Vercel AI SDK to a Steel browser session? Inside a `tool()`'s `execute`, call `steel.sessions.create()` and connect with `chromium.connectOverCDP()` using the session's `websocketUrl` plus your `apiKey`. Subsequent tools (navigate, snapshot, extract) drive that browser and return typed results. ### Does the Vercel AI SDK work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — pass them to `sessions.create()` (e.g. `useProxy`, `solveCaptcha`, `stealthConfig`). They're session-creation options and don't touch the AI SDK's tool or streaming layers. ### Can users watch the browser while the agent runs in a chat UI? Yes — the tool returns `liveViewUrl` (`session.sessionViewerUrl`), and the Next.js recipe embeds Steel's Live View iframe alongside the chat so users watch the browser as the agent works. ### Which model providers can I use? Any AI SDK-supported provider — install a provider package like `@ai-sdk/anthropic` and bring an Anthropic, OpenAI, or other provider key. Steel only needs the CDP connection, so the model choice is independent. For current model recommendations, see the [Steel leaderboard](https://leaderboard.steel.dev/). ### Resources * [Vercel AI SDK documentation](https://ai-sdk.dev/) – Tools, agents, streaming, and providers * [Steel Sessions API reference](/api-reference) – Programmatic session control for Steel browsers * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Run Browser Use in the Cloud on Steel URL: https://docs.steel.dev/integrations/browser-use The Browser Use integration connects Steel's browser infrastructure with the [Browser Use agent framework](/cookbook/topics/browser-use), enabling AI models to perform complex web interactions. Agents can navigate websites, fill forms, click buttons, extract data, and complete multi-step tasks – all while leveraging Steel's reliable cloud browsers for execution. This integration bridges the gap between AI capabilities and real-world web applications without requiring custom API development. ### Requirements * **Steel API Key**: Active Steel subscription * **Python**: 3.11+ * **Supported models**: vision-capable models like GPT-5, Claude Sonnet 4, or Gemini 3 Pro ### Connect Steel to Browser Use Pass Steel's CDP URL into a Browser Use `BrowserSession`: ```python from browser_use import Agent, BrowserSession from browser_use.llm import ChatOpenAI from steel import Steel client = Steel(steel_api_key=STEEL_API_KEY) session = client.sessions.create() cdp_url = f"{session.websocket_url}&apiKey={STEEL_API_KEY}" agent = Agent( task="Find the latest news on Steel.dev", llm=ChatOpenAI(model="gpt-5", api_key=OPENAI_API_KEY), browser_session=BrowserSession(cdp_url=cdp_url), ) result = await agent.run() ``` Full runnable starters: * Connect Browser Use to a Steel cloud browser: [Steel + Browser Use recipe →](/cookbook/browser-use) * Auto-solve captchas with Steel + Browser Use: [Captcha auto recipe →](/cookbook/browser-use-captcha-auto) * Hand off captchas to a human via Steel Live View: [Manual captcha recipe →](/cookbook/browser-use-captcha-manual) ### FAQ ### Do I need to change my existing Browser Use code to use Steel? No — pass a `BrowserSession(cdp_url=...)` into your `Agent` and Browser Use drives Steel's cloud browser instead of a local one. Your task, LLM config, and `agent.run()` loop stay the same. ### How do I connect Browser Use to a Steel browser session? Create a session with `client.sessions.create()`, build the CDP URL as `f"{session.websocket_url}&apiKey={STEEL_API_KEY}"`, and pass it to `BrowserSession(cdp_url=cdp_url)` on the `Agent`. ### Does Browser Use work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — these are session-creation options (e.g. `use_proxy`, `solve_captcha`, `stealth_config` on `sessions.create`), invisible to Browser Use itself. The page links dedicated recipes for auto-solving CAPTCHAs and handing them to a human. ### Which LLMs work with Browser Use on Steel? Vision-capable models — the page calls out GPT-5, Claude Sonnet 4, and Gemini 3 Pro, and the example wires `ChatOpenAI(model="gpt-5")`. You also need Python 3.11+. For up-to-date model recommendations for browser agents, check the [Steel leaderboard](https://leaderboard.steel.dev/). ### Can a human take over when the agent hits a CAPTCHA? Yes — Steel's Live View lets a person solve the CAPTCHA in the running session while the agent waits. The page links a manual-captcha recipe showing this hand-off pattern. ### Resources * [Browser Use documentation](https://docs.browser-use.com/) – Comprehensive guide to the browser-use library * [Browser Use examples](https://github.com/browser-use/browser-use/tree/main/examples) – Working example implementations * [Browser Use Discord](https://link.browser-use.com/discord) – Join discussions and get support * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Claude Agent SDK + Steel Cloud Browsers URL: https://docs.steel.dev/integrations/claude-agent-sdk The Claude Agent SDK is the engine behind Claude Code, exposed as a Python and TypeScript library. You hand `query()` a prompt and an options object and iterate the typed messages it streams back. The Steel integration exposes a cloud browser as in-process MCP tools, so the SDK runs the agent loop and Steel handles the browser. Available in TypeScript and Python. ### Requirements * **Steel API Key**: Active Steel subscription * **Anthropic API Key**: Access to a Claude 4 model * **Runtime**: Node.js 20+ or Python 3.10+ * **Packages**: `@anthropic-ai/claude-agent-sdk` or `claude-agent-sdk`, plus `steel-sdk` and `playwright` ### Connect Steel to the Claude Agent SDK Wrap a Steel session in a `tool()` and bundle it into an in-process MCP server: ```typescript import { createSdkMcpServer, query, tool } from "@anthropic-ai/claude-agent-sdk"; import { chromium } from "playwright"; import Steel from "steel-sdk"; const steel = new Steel({ steelAPIKey: STEEL_API_KEY }); const openSession = tool( "open_session", "Open a Steel cloud browser session.", {}, async () => { const session = await steel.sessions.create({}); const browser = await chromium.connectOverCDP( `${session.websocketUrl}&apiKey=${STEEL_API_KEY}`, ); return { content: [ { type: "text", text: JSON.stringify({ sessionId: session.id }) }, ], }; }, ); const steelServer = createSdkMcpServer({ name: "steel", version: "1.0.0", tools: [openSession], }); ``` Pass the server into `query()` via `mcpServers` and pre-approve calls with `allowedTools: ["mcp__steel__*"]`. Drop the SDK's built-in tools with `tools: []` so the agent only sees Steel. Full runnable starter: [Steel + Claude Agent SDK recipe →](/cookbook/claude-agent-sdk) Steel runs the same way across [other agent frameworks](/cookbook/topics/agents). ### FAQ ### Do I need to change my existing Claude Agent SDK code to use Steel? No — Steel is exposed as in-process MCP tools. Wrap a Steel session in a `tool()`, bundle it with `createSdkMcpServer`, and your `query()` loop and message handling stay exactly the same. ### How do I connect the Claude Agent SDK to a Steel browser session? Define a `tool()` that calls `steel.sessions.create()` and connects via `chromium.connectOverCDP()` with the session's `websocketUrl` plus `apiKey`, bundle it into an in-process MCP server with `createSdkMcpServer`, then pass that server to `query()` via `mcpServers` and pre-approve calls with `allowedTools`. ### Does the Claude Agent SDK work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — enable them when your tool creates the session (e.g. `useProxy`, `solveCaptcha`, `stealthConfig` on `sessions.create()`). The SDK's agent loop and MCP plumbing are unaffected. ### Is the Steel integration available in both TypeScript and Python? Yes — use `@anthropic-ai/claude-agent-sdk` for TypeScript or `claude-agent-sdk` for Python, plus `steel-sdk` and `playwright`. You'll also need an Anthropic API key with access to a Claude 4 model. ### Resources * [Claude Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview) – Agent loop, custom MCP tools, hooks, subagents * [Steel Sessions API reference](/api-reference) – Programmatic session control for Steel browsers * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Claude Code URL: https://docs.steel.dev/integrations/claude-code The Claude Code integration gives Claude Code a real cloud browser through the Steel CLI. From a Claude Code session, you can start and control Steel sessions, scrape rendered pages, run computer-use actions, watch live browser state through the session viewer, and turn successful runs into repeatable scripts. Claude Code already works well with shell commands; Steel adds the browser surface for sites that need JavaScript, session state, or interactive navigation. Steel works the same way with [other agents and frameworks](/cookbook/topics/agents), from CrewAI to LangGraph. ### Requirements * **Node.js**: Version 18 or higher * **Claude Code**: Installed locally * **Steel CLI**: Installed locally * **Steel API Key**: Active Steel account ### Setup #### Step 1: Install Steel CLI ```bash curl -LsSf https://setup.steel.dev | sh ``` #### Step 2: Log in ```bash steel login ``` #### Step 3: Install the browser skill (recommended) The `steel-browser` skill gives Claude Code better command discovery and more reliable browser workflows. ```bash npx skills add steel-dev/skills --skill steel-browser -a claude-code -g ``` Restart Claude Code after installing so it can discover the skill. ### Authenticated workflows For authenticated sites, prepare reusable auth state in Steel ahead of time rather than asking Claude Code to handle login from scratch during every run. See: * [Profiles API](/overview/profiles-api/overview) * [Reusing Auth Context](/overview/sessions-api/reusing-auth-context) ### Live debugging Steel sessions return a viewer URL that makes it easier to monitor what the agent is doing in real time. This is useful when Claude Code reaches a modal, a sign-in wall, or a page that does not behave as expected. ### Repeatable workflows After a successful run, Claude Code can help turn the browser workflow into something more repeatable: * A bash script for local execution * A project-specific command or workflow * A documented runbook for recurring tasks ### Constraints * **Command approvals depend on your Claude Code settings.** Shell access may require approval depending on your permission mode. * **First runs are usually the roughest.** Dynamic web apps often need a few retries before the workflow is stable. * **Authenticated sites work best with prepared Steel auth state.** Reusing profiles or auth context is generally more reliable than repeated interactive logins. ### FAQ ### Do I need to write integration code to use Steel with Claude Code? No — the integration works through the Steel CLI. Install it with `curl -LsSf https://setup.steel.dev | sh`, run `steel login`, and Claude Code can start and control Steel sessions, scrape rendered pages, and run computer-use actions from the terminal. ### How does Claude Code connect to a Steel browser session? Through Steel CLI commands in its shell. For better command discovery and more reliable workflows, install the `steel-browser` skill with `npx skills add steel-dev/skills --skill steel-browser -a claude-code -g` and restart Claude Code so it discovers the skill. ### Does Claude Code work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — those are properties of the Steel session itself, not the client driving it. Sessions Claude Code starts run on the same Sessions API that supports `useProxy`, `solveCaptcha`, and `stealthConfig` at creation time. ### How should I handle sites that require login? Prepare reusable auth state in Steel ahead of time via the Profiles API or Reusing Auth Context, rather than asking Claude Code to log in from scratch every run. The page calls prepared auth state more reliable than repeated interactive logins. ### Can I watch what Claude Code is doing in the browser? Yes — Steel sessions return a viewer URL for monitoring the browser in real time. That's especially useful when Claude Code hits a modal, a sign-in wall, or a page that misbehaves, and successful runs can then be turned into scripts or runbooks. ### Resources * [Give Claude Code a real browser](https://steel.dev/blog/give-claude-code-a-real-browser) – Blog post on using Claude Code with Steel * [Claude Code overview](https://code.claude.com/docs/en/overview) – Official Claude Code documentation * [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works) – Built-in tools, permissions, and execution model * [Steel CLI docs](/overview/steel-cli) – Full command reference and workflows * [Steel Skills](/overview/skills) – Installable skills for coding agents * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Claude Computer Use URL: https://docs.steel.dev/integrations/claude-computer-use The Claude Computer Use integration runs Anthropic's [vision-based agent loop](/cookbook/topics/computer-use) on a Steel browser session. Claude takes screenshots through Steel, decides the next action (click, type, scroll), and Steel executes it, so you can automate complex web tasks without writing custom selectors. It pairs well with Steel's anti-bot capabilities, proxy support, and sandboxed environments. ### Requirements * **Anthropic API Key**: A Claude 4 model with computer use * **Steel API Key**: Active Steel subscription * **Runtime**: Python 3.10+ or Node.js 20+ * **Note**: Anthropic's computer-use tool is in beta ### Connect Steel to Claude Steel's `sessions.computer` API takes screenshots and executes actions; pair it with Claude's `computer_20251124` tool (with the `computer-use-2025-11-24` beta header): ```typescript import { Steel } from "steel-sdk"; const steel = new Steel({ steelAPIKey: STEEL_API_KEY }); const session = await steel.sessions.create({ dimensions: { width: 1024, height: 768 }, }); // Take a screenshot via Steel const { base64_image } = await steel.sessions.computer(session.id, { action: "take_screenshot", }); // Send to Claude with the computer-use tool, then route Claude's // returned actions back through `steel.sessions.computer({ action: ... })`. ``` Full runnable starters: * Build a Claude Computer Use loop on Steel: [Steel + Claude Computer Use recipe →](/cookbook/claude-computer-use) * Drive a mobile-viewport Steel session with Claude: [Mobile recipe →](/cookbook/claude-computer-use-mobile) ### FAQ ### Do I need Playwright or CSS selectors to use Claude Computer Use with Steel? No — Claude's computer-use loop is vision-based. Claude looks at screenshots, decides actions like click, type, or scroll, and Steel executes them through its `sessions.computer` API, so there are no custom selectors to write. ### How do I connect Claude Computer Use to a Steel browser session? Create a session with explicit `dimensions` (the example uses 1024x768), take screenshots via `steel.sessions.computer(session.id, { action: "take_screenshot" })`, send the `base64_image` to Claude's `computer_20251124` tool, and route Claude's returned actions back through `steel.sessions.computer({ action: ... })`. ### Does Claude Computer Use work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — the page notes it pairs well with Steel's anti-bot capabilities, proxy support, and sandboxed environments. These are enabled at session creation (e.g. `useProxy`, `solveCaptcha`, `stealthConfig`) and don't change the agent loop. ### How does the screenshot/action loop actually work? Steel takes a screenshot, you send it to Claude with the computer-use tool, Claude returns the next action (click, type, scroll), and Steel executes it via `sessions.computer` — then you screenshot again and repeat until the task completes. ### Resources * [Anthropic Computer Use documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) – Official documentation from Anthropic * [Steel Sessions API reference](/api-reference) – Technical details for managing Steel browser sessions * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Codex URL: https://docs.steel.dev/integrations/codex The Codex integration gives Codex a real cloud browser through the Steel CLI. From a Codex session, you can start and control Steel sessions, scrape rendered pages, run computer-use actions, and turn one-off runs into reusable scripts. Codex and Steel fit together well because both are command-line tools. The same CLI setup works with [other agents and frameworks](/cookbook/topics/agents) too. Once Steel CLI is on your `PATH`, Codex can inspect command help, run the commands it needs, and verify results from the terminal. ### Requirements * **Node.js**: Version 18 or higher * **Codex CLI**: Installed locally * **Steel CLI**: Installed locally * **Steel API Key**: Active Steel account ### Setup #### Step 1: Install Steel CLI ```bash curl -LsSf https://setup.steel.dev | sh ``` #### Step 2: Log in ```bash steel login ``` #### Step 3: Install the browser skill (recommended) The `steel-browser` skill gives Codex better command discovery and more consistent browser workflows. ```bash npx skills add steel-dev/skills --skill steel-browser -a codex -g ``` Restart Codex after installing so it can discover the skill. ### Automation workflow After a successful manual run, you can ask Codex to turn the workflow into a script: ``` Write a bash script based on what you just did. ``` That works well for jobs like recurring research, internal reporting, or lightweight monitoring. A common pattern is: 1. Run the task once interactively 2. Convert it into a script 3. Schedule it with cron or another runner ### Constraints * **Command approvals depend on your Codex settings.** Codex may ask before running shell commands unless you have configured a more permissive approval mode. * **Authenticated workflows usually need preconfigured Steel auth state.** For reusable login state, see [Profiles API](/overview/profiles-api/overview) and [Reusing Auth Context](/overview/sessions-api/reusing-auth-context). ### FAQ ### Do I need to write integration code to use Steel with Codex? No — the integration works through the Steel CLI. Install it with `curl -LsSf https://setup.steel.dev | sh`, run `steel login`, and Codex can start and control Steel sessions, scrape rendered pages, and run computer-use actions from the terminal. ### How does Codex connect to a Steel browser session? Once Steel CLI is on your `PATH`, Codex inspects command help, runs the commands it needs, and verifies results from the terminal. For better command discovery, install the `steel-browser` skill with `npx skills add steel-dev/skills --skill steel-browser -a codex -g` and restart Codex. ### Does Codex work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — those are properties of the Steel session, not of Codex. Sessions started from the CLI run on the same Sessions API that supports `useProxy`, `solveCaptcha`, and `stealthConfig` at creation time. ### How do I turn a one-off Codex browser run into a recurring job? After a successful manual run, prompt Codex with "Write a bash script based on what you just did", then schedule the script with cron or another runner. The page recommends this run-once, convert, schedule pattern for recurring research, reporting, and monitoring. ### What should I know before pointing Codex at authenticated sites? Authenticated workflows usually need preconfigured Steel auth state — set up reusable login state via the Profiles API or Reusing Auth Context instead of interactive logins each run. Also note Codex may ask for command approvals depending on your approval mode. ### Resources * [Codex + Steel + Resend blog post](https://steel.dev/blog/codex-wired-steel-and-resend-into-a-daily-newsletter) – Example workflow for building a daily newsletter with Codex * [Codex CLI docs](https://developers.openai.com/codex/cli) – Install and use Codex locally * [Steel CLI docs](/overview/steel-cli) – Full command reference and workflows * [Steel Skills](/overview/skills) – Installable skills for coding agents * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Build a CrewAI Browser Agent on Steel URL: https://docs.steel.dev/integrations/crewai CrewAI is a Python framework for orchestrating [multi-agent workflows](/cookbook/topics/agents) with autonomous teams (crews) and event-driven flows. The Steel integration exposes a Steel browser as a CrewAI tool, so your crew can search, navigate, fill forms, extract data, and validate results across collaborating agents. You can mix autonomy with precise control, share memory across steps, return structured outputs, and add human-in-the-loop checkpoints for sensitive actions. ### Requirements * **Steel API Key**: Active Steel subscription * **LLM API key**: OpenAI or any CrewAI-supported provider * **Python**: 3.10–3.13 ### Connect Steel to CrewAI Expose Steel as a CrewAI `BaseTool` your agents can call: ```python import os from crewai.tools import BaseTool from steel import Steel class SteelScrapeTool(BaseTool): name: str = "Steel web scrape" description: str = "Scrape webpages with Steel and return markdown" def __init__(self): super().__init__() self._steel = Steel(steel_api_key=os.environ["STEEL_API_KEY"]) def _run(self, url: str): return self._steel.scrape(url=url, format=["markdown"]) ``` Full runnable starter: [Steel + CrewAI recipe →](/cookbook/crewai) ### FAQ ### Do I need to change my existing CrewAI code to use Steel? No — Steel plugs in as a regular CrewAI tool. Define a `BaseTool` subclass whose `_run` method calls Steel, hand it to your agents, and your crews, flows, and memory setup stay untouched. ### How do I connect CrewAI to Steel? Expose Steel as a CrewAI `BaseTool`: instantiate the Steel client in `__init__` and call it from `_run`. The page's example tool scrapes a URL with `self._steel.scrape(url=url, format=["markdown"])` and returns markdown to the agent. ### Does CrewAI work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — when your tool creates Steel sessions you can enable these at session creation (e.g. `use_proxy`, `solve_captcha`, `stealth_config`). They're Steel-side options, so CrewAI's orchestration doesn't change. ### Do I need a full browser session, or is scraping enough for a crew? For read-only research, the page's tool uses Steel's `scrape` API to return page markdown — no session management needed. For interactive flows (forms, clicks, multi-step navigation), create a Steel session inside the tool instead. ### Resources * [CrewAI documentation](https://docs.crewai.com/) – Official documentation for CrewAI * [CrewAI examples repo](https://github.com/crewAIInc/crewAI-examples) – Real-world starter crews (trip planner, stock analysis, job posts) * [Steel Sessions API reference](/api-reference) – Programmatically manage Steel browser sessions * [Steel Discord](https://discord.gg/steel-dev) – Share recipes and get help # Gemini Computer Use URL: https://docs.steel.dev/integrations/gemini-computer-use The Gemini Computer Use integration runs Gemini 3's [vision-based agent loop](/cookbook/topics/computer-use) on a Steel browser session. Gemini takes screenshots through Steel, decides the next action (click, type, scroll), and Steel executes it, so you can automate complex web tasks without writing custom selectors. It pairs well with Steel's anti-bot capabilities, proxy support, and sandboxed environments. ### Requirements * **Gemini API Key**: A Gemini 3 model with computer use * **Steel API Key**: Active Steel subscription * **Runtime**: Python 3.10+ or Node.js 20+ ### Connect Steel to Gemini Steel's `sessions.computer` API takes screenshots and executes actions; pair it with Gemini 3's built-in computer use: ```typescript import { Steel } from "steel-sdk"; const steel = new Steel({ steelAPIKey: STEEL_API_KEY }); const session = await steel.sessions.create({ dimensions: { width: 1280, height: 800 }, }); // Take a screenshot via Steel const { base64_image } = await steel.sessions.computer(session.id, { action: "take_screenshot", }); // Send to Gemini with the computer-use tool, then route Gemini's // returned actions back through `steel.sessions.computer({ action: ... })`. ``` Full runnable starter: [Steel + Gemini Computer Use recipe →](/cookbook/gemini-computer-use) ### FAQ ### Do I need Playwright or CSS selectors to use Gemini Computer Use with Steel? No — Gemini's loop is vision-based. Gemini reads screenshots, decides actions like click, type, or scroll, and Steel executes them via its `sessions.computer` API, so no custom selectors are needed. ### How do I connect Gemini Computer Use to a Steel browser session? Create a session with explicit `dimensions` (the example uses 1280x800), take a screenshot with `steel.sessions.computer(session.id, { action: "take_screenshot" })`, send the `base64_image` to Gemini 3 with its built-in computer-use tool, and route Gemini's returned actions back through `steel.sessions.computer({ action: ... })`. ### Does Gemini Computer Use work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — the page notes it pairs well with Steel's anti-bot capabilities, proxy support, and sandboxed environments. These are session-creation options (e.g. `useProxy`, `solveCaptcha`, `stealthConfig`) and don't change the agent loop. ### Which Gemini model do I need, and how does the loop work? A Gemini 3 model with computer use — the tool is built in. Steel screenshots the session, Gemini decides the next action, Steel executes it via `sessions.computer`, and the loop repeats until the task completes. Consult the [Steel leaderboard](https://leaderboard.steel.dev/) for the most recent model recommendations. ### Resources * [Gemini Computer Use documentation](https://ai.google.dev/gemini-api/docs/computer-use) – Official documentation from Google * [Steel Sessions API reference](/api-reference) – Technical details for managing Steel browser sessions * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Hermes Agent URL: https://docs.steel.dev/integrations/hermes-agent The Steel integration for Hermes is currently pending upstream. It is being developed in [NousResearch/hermes-agent PR #5555](https://github.com/NousResearch/hermes-agent/pull/21182) and may change before it lands in a Hermes release. Upvote or comment on the PR to signal interest. The pending Hermes integration adds Steel as a cloud browser provider inside Hermes. Based on the current upstream pull request, the integration is expected to provide: * Steel as a selectable browser provider during Hermes setup * Steel-backed browser sessions for web navigation and interaction * A `steel_scrape` tool for server-side content extraction * Support for Steel-specific options such as proxying and CAPTCHA solving * Viewer URL support so you can monitor browser sessions while the agent runs If this ships as proposed, Hermes users will be able to route browser tasks through Steel by setting `STEEL_API_KEY` and selecting Steel in Hermes configuration. Meanwhile, [other agent frameworks](/cookbook/topics/agents) already route browser tasks through Steel today. ### Requirements * **Hermes Agent**: A build that includes the Steel integration from PR #5555 or a future release that ships it * **Steel API Key**: Active Steel account ### Expected setup flow The workflow below reflects the current pull request, not a released Hermes build. ```bash hermes setup ``` During setup: 1. Choose your model provider 2. Select Steel as the browser provider 3. Add your `STEEL_API_KEY` If you are using a current release of Hermes and do not see Steel in the setup flow, that is expected until the integration lands upstream. To try it now, check out the PR branch and run Hermes from source. ### Expected workflow Once the integration is available, Hermes should be able to use Steel for tasks that need a real browser: ``` Find a hotel near Grand Central and compare the top options. ``` In the proposed implementation, Hermes would start a Steel session, browse the relevant sites, and return a viewer URL alongside the task output so you can inspect the session while it runs. ### Constraints * **This integration is not yet part of a released Hermes build.** Check the upstream PR or Hermes changelog before relying on it. * **The setup flow may change before release.** Provider names, environment variables, or supported options may still be updated. * **Documentation should be validated against the released Hermes version once the PR lands.** ### Resources * [Steel is now a native browser provider in Hermes](https://steel.dev/blog/steel-is-now-a-native-browser-provider-in-hermes) – Blog post covering the Hermes integration * [Hermes Agent repository](https://github.com/NousResearch/hermes-agent) – Upstream project * [Steel integration PR #5555](https://github.com/NousResearch/hermes-agent/pull/5555) – Proposed Steel provider implementation * [Steel CLI docs](/overview/steel-cli) – Steel browser workflows from the terminal * [Steel Sessions API reference](/api-reference) – Programmatic session management * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Integrations URL: https://docs.steel.dev/integrations # Build a LangGraph Browser Agent on Steel URL: https://docs.steel.dev/integrations/langgraph [LangGraph](https://langchain-ai.github.io/langgraph/) builds agents as state machines: nodes do work, edges route control, and the agent loop is something you compose explicitly rather than something the framework hides for you. LangChain ships the model wrappers and `@tool` decorator; LangGraph ships the runtime, plus prebuilt `ToolNode` and `tools_condition` helpers that turn three nodes and four edges into a [tool-calling agent](/cookbook/topics/agents). The Steel integration runs each `@tool` against a Steel cloud session, so the agent loop drives a real browser. ### Requirements * **Steel API Key**: Active Steel subscription * **Model provider key**: Anthropic, OpenAI, or any other LangChain-supported provider * **Python**: 3.10+ * **Packages**: `langgraph`, `langchain-anthropic` (or another `langchain-*` provider), `steel-sdk`, `playwright` ### Connect Steel to LangGraph Define `@tool` functions that drive a Steel-backed Playwright `page`, build a `StateGraph` with `agent` and `tools` nodes, and wire `tools_condition` between them: ```python from langchain_anthropic import ChatAnthropic from langchain_core.tools import tool from langgraph.graph import END, START, MessagesState, StateGraph from langgraph.prebuilt import ToolNode, tools_condition from playwright.async_api import async_playwright from steel import Steel steel = Steel(steel_api_key=STEEL_API_KEY) @tool async def open_session() -> dict: """Open a Steel cloud browser session.""" global _page session = steel.sessions.create() playwright = await async_playwright().start() browser = await playwright.chromium.connect_over_cdp( f"{session.websocket_url}&apiKey={STEEL_API_KEY}" ) _page = browser.contexts[0].pages[0] return {"session_id": session.id, "live_view_url": session.session_viewer_url} tools = [open_session] model = ChatAnthropic(model="claude-haiku-4-5").bind_tools(tools) async def agent_node(state: MessagesState) -> dict: return {"messages": [await model.ainvoke(state["messages"])]} graph = StateGraph(MessagesState) graph.add_node("agent", agent_node) graph.add_node("tools", ToolNode(tools)) graph.add_edge(START, "agent") graph.add_conditional_edges("agent", tools_condition) graph.add_edge("tools", "agent") app = graph.compile() ``` `tools_condition` routes to `"tools"` when the assistant message has tool calls and to `END` when it doesn't. The `tools -> agent` edge is what makes it a loop. For a typed final answer, add a `format` node that runs `model.with_structured_output(Schema)` on the conversation; for one-line wiring, swap the explicit graph for `langgraph.prebuilt.create_react_agent(model, tools, response_format=Schema)`. Full runnable starter: [Steel + LangGraph recipe →](/cookbook/langgraph) ### FAQ ### Do I need to change my existing LangGraph code to use Steel? No — your `StateGraph`, nodes, and edges stay the same. Steel lives inside your `@tool` functions: a tool creates a session and attaches Playwright via `connect_over_cdp`, and the agent loop drives that page. ### How do I connect LangGraph to a Steel browser session? Inside a `@tool`, call `steel.sessions.create()` and connect Playwright with `chromium.connect_over_cdp(f"{session.websocket_url}&apiKey={STEEL_API_KEY}")`, then use `browser.contexts[0].pages[0]` as the shared page for your other tools. ### Does LangGraph work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — enable them when the tool creates the session (e.g. `use_proxy`, `solve_captcha`, `stealth_config` on `sessions.create()`). The graph and `ToolNode` wiring are unaffected. ### How does the agent loop actually work in the LangGraph example? `tools_condition` routes to the `"tools"` node when the assistant message contains tool calls and to `END` when it doesn't, and the `tools -> agent` edge closes the loop. Three nodes and four edges give you a complete tool-calling browser agent. ### Resources * [LangGraph documentation](https://langchain-ai.github.io/langgraph/) – State graphs, prebuilts, checkpointing, and streaming * [LangChain `@tool` reference](https://python.langchain.com/docs/concepts/tools/) – Tool definitions and Pydantic schemas * [LangSmith](https://smith.langchain.com) – Tracing for every node and tool call * [Steel Sessions API reference](/api-reference) – Programmatic session control for Steel browsers * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Magnitude URL: https://docs.steel.dev/integrations/magnitude Magnitude is a TypeScript [browser-agent framework](/cookbook/topics/agents) that turns natural-language prompts into typed actions. The Steel integration runs Magnitude's planning loop on a Steel cloud browser, so you can drive a real session from prompts and end with structured outputs validated against a schema. Good fit for research-style flows that mix navigation and extraction. ### Requirements * **Steel API Key**: Active Steel subscription * **Anthropic API Key**: Magnitude's default planning model * **Node.js**: v20+ ### Connect Steel to Magnitude Pass Steel's CDP URL into Magnitude's `startBrowserAgent` config: ```typescript import { startBrowserAgent } from "magnitude-core"; import { Steel } from "steel-sdk"; const client = new Steel({ steelAPIKey: STEEL_API_KEY }); const session = await client.sessions.create({}); const agent = await startBrowserAgent({ url: "https://github.com/steel-dev/leaderboard", llm: { provider: "anthropic", options: { model: "claude-sonnet-4-6", apiKey: ANTHROPIC_API_KEY }, }, browser: { cdp: `${session.websocketUrl}&apiKey=${STEEL_API_KEY}` }, }); ``` Full runnable starter: [Steel + Magnitude recipe →](/cookbook/magnitude) ### FAQ ### Do I need to change my existing Magnitude code to use Steel? No — add `browser: { cdp: ... }` to your `startBrowserAgent` config and Magnitude's planning loop runs on the Steel cloud browser. Prompts, typed actions, and structured outputs work as before. ### How do I connect Magnitude to a Steel browser session? Create a session with `client.sessions.create()`, then set `browser.cdp` in the `startBrowserAgent` config to the session's `websocketUrl` with your `apiKey` appended. ### Does Magnitude work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — configure them when creating the session (e.g. `useProxy`, `solveCaptcha`, `stealthConfig` on `sessions.create()`). Magnitude just connects to the resulting CDP endpoint. ### Which model does Magnitude use for planning? Anthropic is Magnitude's default planning provider — the example configures `llm: { provider: "anthropic", options: { model: "claude-sonnet-4-6" } }`. You need an Anthropic API key plus Node.js 20+. ### Resources * [Magnitude documentation](https://docs.magnitude.run/) – Concepts, agent APIs, and examples * [Steel Sessions API reference](/api-reference) – Programmatic session control for Steel browsers * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Mastra URL: https://docs.steel.dev/integrations/mastra [Mastra](https://mastra.ai/) is a TypeScript framework that wraps the Vercel AI SDK with its own primitives: typed `createTool` definitions with input *and* output schemas, a top-level `Mastra` registry that wires agents into storage and observability, a Model Router that turns `'anthropic/claude-haiku-4-5'` into a working client without a provider package install, and a built-in Studio playground (`mastra dev`) for chatting with your agents and replaying traces. The Steel integration runs each tool against a Steel cloud session, so the agent's tool surface is "drive a real browser" without leaving the Mastra primitives. ### Requirements * **Steel API Key**: Active Steel subscription * **Node.js**: v22.13+ * **Packages**: `@mastra/core`, `steel-sdk`, `playwright`, `zod` * **Model provider key**: Anthropic, OpenAI, Google, or any other provider supported by the Mastra Model Router ### Connect Steel to Mastra Define a `createTool` that opens a Steel session, register it on an `Agent`, and attach the agent to a top-level `Mastra` registry: ```typescript import { Mastra } from "@mastra/core"; import { Agent } from "@mastra/core/agent"; import { createTool } from "@mastra/core/tools"; import { chromium } from "playwright"; import Steel from "steel-sdk"; import { z } from "zod"; const steel = new Steel({ steelAPIKey: process.env.STEEL_API_KEY! }); const openSession = createTool({ id: "open-session", description: "Open a Steel cloud browser session.", inputSchema: z.object({}), outputSchema: z.object({ sessionId: z.string(), liveViewUrl: z.string(), }), execute: async () => { const session = await steel.sessions.create({}); const browser = await chromium.connectOverCDP( `${session.websocketUrl}&apiKey=${process.env.STEEL_API_KEY}`, ); return { sessionId: session.id, liveViewUrl: session.sessionViewerUrl }; }, }); const researchAgent = new Agent({ id: "research-agent", name: "Steel Research", instructions: "You operate a Steel cloud browser via tools. ...", model: "anthropic/claude-haiku-4-5", tools: { openSession }, }); export const mastra = new Mastra({ agents: { researchAgent } }); ``` Tools are passed as a record (not an array): the keys are what the model sees as tool names. With the registry wired up, `npx mastra dev` opens Studio at `http://localhost:4111` so you can chat with `research-agent` and inspect its tool calls live. Full runnable starter: [Steel + Mastra recipe →](/cookbook/mastra) Steel runs the same way across [other agent frameworks](/cookbook/topics/agents). ### FAQ ### Do I need to change my existing Mastra code to use Steel? No — Steel lives inside a standard `createTool` definition whose `execute` opens a session and connects Playwright over CDP. Your `Agent`, the `Mastra` registry, Model Router strings, and Studio all work unchanged. ### How do I connect Mastra to a Steel browser session? Define a `createTool` whose `execute` calls `steel.sessions.create()` and connects via `chromium.connectOverCDP()` with the session's `websocketUrl` plus `apiKey`, register it on an `Agent` via `tools`, and attach the agent to a top-level `Mastra` registry. ### Does Mastra work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — pass the options to `sessions.create()` inside your tool (e.g. `useProxy`, `solveCaptcha`, `stealthConfig`). Mastra's tool layer is unaffected because these are Steel session settings. ### Resources * [Mastra documentation](https://mastra.ai/docs) – Agents, tools, workflows, memory, and Studio * [Mastra Model Router](https://mastra.ai/blog/model-router) – Provider-agnostic model strings * [Mastra Studio](https://mastra.ai/docs/studio/overview) – Local playground for agents and workflows * [Steel Sessions API reference](/api-reference) – Programmatic session control for Steel browsers * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Notte URL: https://docs.steel.dev/integrations/notte Notte is a Python framework for building [reliable web agents](/cookbook/topics/agents) with stable navigation and structured outputs. The Steel integration connects a Notte session to a Steel browser, so Notte handles the agent loop and Steel handles the cloud browser plumbing. Use it for tasks where reliable navigation and typed outputs matter more than autonomy. ### Requirements * **Steel API Key**: Active Steel subscription * **Gemini API Key** (or another supported provider): Notte's default model is Gemini * **Python**: 3.11+ ### Connect Steel to Notte Pass Steel's CDP URL into a `notte.Session`: ```python import notte from steel import Steel client = Steel(steel_api_key=STEEL_API_KEY) session = client.sessions.create() cdp_url = f"{session.websocket_url}&apiKey={STEEL_API_KEY}" with notte.Session(cdp_url=cdp_url) as notte_session: agent = notte.Agent( session=notte_session, reasoning_model="gemini/gemini-2.5-flash", ) response = agent.run(task="Go to Wikipedia and search for machine learning") ``` Full runnable starter: [Steel + Notte recipe →](/cookbook/notte) ### FAQ ### Do I need to change my existing Notte code to use Steel? No — pass `cdp_url` into `notte.Session` and Notte runs its agent loop against the Steel browser. Your `notte.Agent` setup and `agent.run(task=...)` calls stay the same. ### How do I connect Notte to a Steel browser session? Create a session with `client.sessions.create()`, build `cdp_url = f"{session.websocket_url}&apiKey={STEEL_API_KEY}"`, and open `notte.Session(cdp_url=cdp_url)` as a context manager, passing it to `notte.Agent(session=notte_session)`. ### Does Notte work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — enable them on `sessions.create()` (e.g. `use_proxy`, `solve_captcha`, `stealth_config`). Notte connects over the CDP URL and is unaware of how the session was provisioned. ### Which model does Notte use by default? Gemini — the requirements call for a Gemini API key (or another supported provider), and the example sets `reasoning_model="gemini/gemini-2.5-flash"` on the agent. Python 3.11+ is required. ### Resources * [Notte documentation](https://docs.notte.cc) – Concepts, agent APIs, and examples * [Steel Sessions API reference](/api-reference) – Programmatic session control for Steel browsers * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # OpenAI Agents SDK + Steel Cloud Browsers URL: https://docs.steel.dev/integrations/openai-agents-sdk The OpenAI Agents SDK is OpenAI's official toolkit for building agents with typed tools, handoffs, guardrails, and tracing. The Steel integration runs each tool against a Steel cloud session, so you can stand up a [typed browser agent](/cookbook/topics/agents) that opens a session, navigates, extracts data, and returns a validated final report. Available in TypeScript and Python. ### Requirements * **Steel API Key**: Active Steel subscription * **OpenAI API Key**: A model supported by the Agents SDK * **Runtime**: Node.js 20+ or Python 3.10+ ### Connect Steel to the OpenAI Agents SDK Open a Steel session inside a typed Agents SDK `tool()`: ```typescript import { tool } from "@openai/agents"; import { chromium } from "playwright"; import Steel from "steel-sdk"; import { z } from "zod"; const steel = new Steel({ steelAPIKey: STEEL_API_KEY }); const openSession = tool({ name: "open_session", description: "Open a Steel cloud browser session.", parameters: z.object({}), execute: async () => { const session = await steel.sessions.create({}); const browser = await chromium.connectOverCDP( `${session.websocketUrl}&apiKey=${STEEL_API_KEY}`, ); return { sessionId: session.id, liveViewUrl: session.sessionViewerUrl }; }, }); ``` Full runnable starter: [Steel + OpenAI Agents SDK recipe →](/cookbook/openai-agents) ### FAQ ### Do I need to change my existing OpenAI Agents SDK code to use Steel? No — Steel slots in as a typed `tool()`. The tool's `execute` opens a Steel session and connects Playwright over CDP; your agents, handoffs, guardrails, and tracing work as before. ### How do I connect the OpenAI Agents SDK to a Steel browser session? Inside a `tool()`'s `execute`, call `steel.sessions.create()` and attach Playwright via `chromium.connectOverCDP()` using the session's `websocketUrl` with your `apiKey` appended. Subsequent tools drive that browser. ### Does the OpenAI Agents SDK work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — pass the options when creating the session (e.g. `useProxy`, `solveCaptcha`, `stealthConfig` on `sessions.create()`). They're transparent to the SDK's tool-calling loop. ### Can I watch what the agent is doing in the browser? Yes — the example tool returns `liveViewUrl` from `session.sessionViewerUrl`, which you can open to watch the session live alongside the agent run. ### Is the Steel integration available in both TypeScript and Python? Yes — the Agents SDK integration works in TypeScript and Python (Node.js 20+ or Python 3.10+). The page's example is TypeScript; the cookbook recipe has the full runnable starter. ### Resources * [OpenAI Agents SDK documentation](https://openai.github.io/openai-agents-js/) – Agents, tools, handoffs, tracing * [Steel Sessions API reference](/api-reference) – Programmatic session control for Steel browsers * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # OpenAI Computer Use URL: https://docs.steel.dev/integrations/openai-computer-use The OpenAI Computer Use integration runs OpenAI's [vision-based agent loop](/cookbook/topics/computer-use) on a Steel browser session. The model takes screenshots through Steel, decides the next action (click, type, scroll), and Steel executes it, so you can automate complex web tasks without writing custom selectors. It pairs well with Steel's anti-bot capabilities, proxy support, and sandboxed environments. ### Requirements * **OpenAI API Key**: An OpenAI model with computer use * **Steel API Key**: Active Steel subscription * **Runtime**: Python 3.10+ or Node.js 20+ ### Connect Steel to OpenAI Steel's `sessions.computer` API takes screenshots and executes actions; pair it with OpenAI's Responses API computer-use tool: ```typescript import { Steel } from "steel-sdk"; const steel = new Steel({ steelAPIKey: STEEL_API_KEY }); const session = await steel.sessions.create({ dimensions: { width: 1024, height: 768 }, }); // Take a screenshot via Steel const { base64_image } = await steel.sessions.computer(session.id, { action: "take_screenshot", }); // Send to OpenAI's Responses API with computer-use, then route returned // actions back through `steel.sessions.computer({ action: ... })`. ``` Full runnable starter: [Steel + OpenAI Computer Use recipe →](/cookbook/openai-computer-use) ### FAQ ### How do I connect OpenAI Computer Use to a Steel browser session? Create a session with explicit `dimensions` (the example uses 1024x768), take a screenshot with `steel.sessions.computer(session.id, { action: "take_screenshot" })`, send the `base64_image` to OpenAI's Responses API computer-use tool, and route returned actions back through `steel.sessions.computer({ action: ... })`. ### Does OpenAI Computer Use work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — the page notes it pairs well with Steel's anti-bot capabilities, proxy support, and sandboxed environments. These are session-creation options (e.g. `useProxy`, `solveCaptcha`, `stealthConfig`) and don't change the agent loop. ### How does the screenshot/action loop work? Steel screenshots the session, you send the image to the Responses API with the computer-use tool, the model returns the next action, and Steel executes it via `sessions.computer` — then the loop repeats until the task is done. ### Resources * [OpenAI Computer Use documentation](https://platform.openai.com/docs/guides/tools-computer-use) – Official documentation from OpenAI * [Steel Sessions API reference](/api-reference) – Technical details for managing Steel browser sessions * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # OpenClaw URL: https://docs.steel.dev/integrations/openclaw The OpenClaw integration gives OpenClaw a real cloud browser through the Steel CLI. Once Steel CLI is on your `PATH`, OpenClaw can run multi-step web tasks, scrape rendered pages, watch live browser state, and work through forms and dynamic pages without writing custom integration code. Good fit for application forms, operational workflows, and browser-driven research. The same setup works with [other agent frameworks](/cookbook/topics/agents) like CrewAI and LangGraph. ### Requirements * **Node.js**: Version 18 or higher * **OpenClaw**: Installed locally * **Steel CLI**: Installed locally * **Steel API Key**: Active Steel account ### Setup #### Step 1: Install Steel CLI ```bash curl -LsSf https://setup.steel.dev | sh ``` #### Step 2: Log in ```bash steel login ``` #### Step 3: Install the browser skill (recommended) The `steel-browser` skill gives OpenClaw better command discovery and more reliable browser workflows. ```bash npx skills add steel-dev/skills --skill steel-browser -a opencode -g ``` Restart OpenClaw after installing so it can discover the skill. ### Example workflow OpenClaw works well on browser tasks that need real interaction. One example is filling out a conference CFP form: finding the right page, inspecting the fields, drafting responses, and working through the submission flow. You can start with a prompt like: ``` I would like to submit an application for the call for speakers for AI Engineer World's Fair. Could you figure out what the fields are, what we need, and how I can apply to become a speaker? ``` From there, OpenClaw can start a Steel session, navigate the form, inspect fields with snapshots, and work through the page step by step. ### Watching the session Steel sessions return a viewer URL so you can watch the browser while the agent works. This is useful on form-heavy flows, especially when the page changes dynamically, a modal blocks progress, or the agent needs a second attempt to recover from a mistake. For longer workflows, Steel also keeps the full session history so you can inspect what happened after the fact. ### Where OpenClaw works best OpenClaw is a strong fit for: * Standard web forms * Multi-step browser workflows * Pages that need JavaScript rendering before the agent can reason about them For tasks that only need page content, `steel scrape` is often the faster option: ```bash steel scrape https://example.com ``` ### Authenticated workflows For sites behind login, prepare reusable auth state in Steel ahead of time rather than asking the agent to log in from scratch every time. See: * [Profiles API](/overview/profiles-api/overview) * [Reusing Auth Context](/overview/sessions-api/reusing-auth-context) ### Constraints * **Command approvals depend on your OpenClaw settings.** Shell access may require approval depending on your configuration. * **Form-heavy workflows can still take time.** Dynamic fields, validation errors, and bot checks add retries and extra browser steps. * **Authenticated sites work best with prepared Steel auth state.** Reusing profiles or auth context is generally more reliable than repeated interactive logins. ### FAQ ### Do I need to write integration code to use Steel with OpenClaw? No — the integration works through the Steel CLI. Install it with `curl -LsSf https://setup.steel.dev | sh`, run `steel login`, and once the CLI is on your `PATH` OpenClaw can run multi-step web tasks, scrape rendered pages, and work through forms without custom integration code. ### How does OpenClaw connect to a Steel browser session? Via Steel CLI commands in its shell. Install the `steel-browser` skill for better command discovery — `npx skills add steel-dev/skills --skill steel-browser -a opencode -g` — then restart OpenClaw so it discovers the skill. ### Does OpenClaw work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — those are properties of the Steel session, not the agent. Sessions OpenClaw starts run on the same Sessions API that supports `useProxy`, `solveCaptcha`, and `stealthConfig` at creation time; the page notes bot checks can still add retries on form-heavy flows. ### When should I use `steel scrape` instead of a full OpenClaw browser session? When you only need page content — `steel scrape https://example.com` is often faster than spinning up an interactive session. Save full sessions for forms, multi-step workflows, and pages that need JavaScript rendering before the agent can reason about them. ### How do I monitor or debug what OpenClaw is doing in the browser? Steel sessions return a viewer URL so you can watch the browser live — useful on form-heavy flows when a modal blocks progress or the agent needs a second attempt. For longer workflows, Steel keeps the full session history for after-the-fact inspection. ### Resources * [OpenClaw + Steel blog post](https://steel.dev/blog/openclaw-steel-browser-let-your-ai-agent-fill-the-forms) – Case study using OpenClaw to work through a CFP submission flow * [Steel CLI docs](/overview/steel-cli) – Full command reference and workflows * [Steel Skills](/overview/skills) – Installable skills for coding agents * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Pi Agent URL: https://docs.steel.dev/integrations/pi-agent This integration is part of Steel's experiments effort. Defaults can change without notice, and stability is not guaranteed. [Pi](https://pi.dev/) is a minimal, extension-first coding agent that ships with no built-in browser; capabilities arrive through `pi install`. The Pi integration installs as a native Pi extension that gives Pi a Steel cloud browser, so Pi can navigate, scrape rendered pages, extract structured data, capture screenshots and PDFs, and fill forms across prompts. Steel plugs into [other agents and frameworks](/cookbook/topics/agents) the same way, with a runnable recipe for each. ### Requirements * **Node.js**: Version 18 or higher * **Pi**: Installed locally * **Steel API Key**: Active Steel account ### Setup #### Step 1: Install the extension ```bash pi install npm:@steel-dev/pi-steel ``` Pi picks up the extension on the next run and the Steel browser tools become available automatically. #### Step 2: Authenticate Set `STEEL_API_KEY` in your environment. Grab a free API key at [app.steel.dev](https://app.steel.dev) if you do not have one yet. ### Available tools Once the extension is installed, Pi has access to a full browser toolset: * `steel_navigate` and `steel_scrape` for fetching pages as text, markdown, or HTML * `steel_extract` for structured data from a JSON schema * `steel_fill_form` for submitting forms * Playwright-backed computer actions (click, scroll, type) for pages that scraping cannot reach * Screenshot and PDF capture, returned as Pi artifacts * `steel_pin_session` to keep a browser alive across prompts, or `STEEL_SESSION_MODE=session` for persistent mode CAPTCHA handling is built in, so most bot-protected pages work without extra configuration. ### Example workflow Pi works well on research tasks that span multiple pages and require both scraping and interaction. A prompt like: ``` Visit apple.com and compare all recent MacBook models. ``` Pi will navigate the Mac lineup, follow links into each model page, and fall back to computer actions and screenshots when sticky navigation or viewport-dependent sections block plain scraping. For bot-protected docs: ``` Visit OpenAI docs and tell us how we can use the latest model. ``` Steel handles the bot-protection layer so Pi sees a normal webpage, reads the current API reference, and returns an up-to-date code example rather than a stale one from training data. ### Structured extraction When you would otherwise parse markdown for prices, specs, or listings, `steel_extract` with a JSON schema is usually the better call. Pi gets typed output directly, which is easier to reason about across multi-step workflows. ### Constraints * **Command approvals depend on your Pi settings.** Extension tools may require approval depending on your configuration. * **First runs are usually the roughest.** Dynamic web apps often need a few retries before the workflow is stable. * **Authenticated sites work best with prepared Steel auth state.** Reusing profiles or auth context is generally more reliable than repeated interactive logins. ### Resources * [pi-steel: we gave Pi a real browser in one command](https://steel.dev/blog/we-gave-pi-agent-a-real-browser) – Blog post on the extension and example runs * [`@steel-dev/pi-steel` on GitHub](https://github.com/steel-dev/pi-steel) – Source and issues * [`@steel-dev/pi-steel` on npm](https://www.npmjs.com/package/@steel-dev/pi-steel) – Package page * [Steel CLI docs](/overview/steel-cli) – Full command reference and workflows * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Run Playwright on Steel Cloud Browsers URL: https://docs.steel.dev/integrations/playwright Playwright is Microsoft's [cross-browser automation library](/cookbook/topics/playwright). The Steel integration attaches Playwright to a Steel cloud session over the Chrome DevTools Protocol, so the rest of your script — `page.goto`, locators, `expect`, tracing — drives a remote browser with stealth, proxies, and a live viewer instead of a local Chromium. No `playwright install`, no headful display, no Chrome on your machine. ### Requirements * **Steel API Key**: Active Steel subscription * **Runtime**: Node.js 20+ or Python 3.10+ * **Package**: `playwright` (TypeScript) or `playwright` (Python) ### Connect Steel to Playwright Pass Steel's CDP URL into `chromium.connectOverCDP()`. Steel returns a context with a page already open, so reuse `browser.contexts()[0]` instead of creating a new one: ```typescript import { chromium } from "playwright"; import Steel from "steel-sdk"; const client = new Steel({ steelAPIKey: STEEL_API_KEY }); const session = await client.sessions.create(); const browser = await chromium.connectOverCDP( `${session.websocketUrl}&apiKey=${STEEL_API_KEY}`, ); const page = browser.contexts()[0].pages()[0]; ``` ```python from playwright.sync_api import sync_playwright from steel import Steel client = Steel(steel_api_key=STEEL_API_KEY) session = client.sessions.create() playwright = sync_playwright().start() browser = playwright.chromium.connect_over_cdp( f"{session.websocket_url}&apiKey={STEEL_API_KEY}" ) page = browser.contexts[0].new_page() ``` Full runnable starter: [Steel + Playwright recipe →](/cookbook/playwright) ### FAQ ### Do I need to change my existing Playwright code to use Steel? No — swap your local launch for `chromium.connectOverCDP()` (or `connect_over_cdp` in Python) pointed at the Steel session's `websocketUrl`. The rest of your script — `page.goto`, locators, `expect`, tracing — runs unchanged against the remote browser. ### How do I connect Playwright to a Steel browser session? Create a session with `client.sessions.create()`, then connect with `chromium.connectOverCDP()` in Node or `playwright.chromium.connect_over_cdp()` in Python, passing the session's `websocketUrl` with your `apiKey` appended as a query parameter. ### Does Playwright work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — those are options on `sessions.create()` (e.g. `useProxy`, `solveCaptcha`, `stealthConfig`), not Playwright settings. Playwright just sees a normal CDP browser; stealth, proxies, and the live viewer come from the Steel session. ### Do I still need to run `playwright install` or have Chrome installed locally? No — the browser runs in Steel's cloud, so there's no `playwright install`, no headful display, and no Chrome on your machine. You only need the `playwright` package and a Steel API key. ### Resources * [Playwright documentation](https://playwright.dev) – Official Playwright docs for TypeScript and Python * [Steel Sessions API reference](/api-reference#tag/sessions) – Technical details for managing Steel browser sessions * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Connect Puppeteer to Steel Cloud Browsers (CDP) URL: https://docs.steel.dev/integrations/puppeteer Puppeteer is Chrome's reference [Node.js automation library](/cookbook/topics/browser-automation). The Steel integration attaches Puppeteer to a Steel cloud session through `puppeteer.connect()`, so `page.goto`, `page.evaluate`, `page.waitForSelector`, and the rest of the surface drive a remote browser. Stealth, proxies, and the live session viewer come from Steel without extra wiring. The package is `puppeteer-core` — there's no Chromium to download because the browser lives on Steel. ### Requirements * **Steel API Key**: Active Steel subscription * **Runtime**: Node.js 20+ * **Package**: `puppeteer-core` ### Connect Steel to Puppeteer Pass Steel's CDP URL into `puppeteer.connect()` as `browserWSEndpoint`. Open a fresh tab with `browser.newPage()`: ```typescript import puppeteer from "puppeteer-core"; import Steel from "steel-sdk"; const client = new Steel({ steelAPIKey: STEEL_API_KEY }); const session = await client.sessions.create(); const browser = await puppeteer.connect({ browserWSEndpoint: `${session.websocketUrl}&apiKey=${STEEL_API_KEY}`, }); const page = await browser.newPage(); ``` Full runnable starter: [Steel + Puppeteer recipe →](/cookbook/puppeteer) ### FAQ ### Do I need to change my existing Puppeteer code to use Steel? No — replace `puppeteer.launch()` with `puppeteer.connect()` and pass Steel's CDP URL as `browserWSEndpoint`. `page.goto`, `page.evaluate`, `page.waitForSelector`, and the rest of the API work unchanged against the remote browser. ### How do I connect Puppeteer to a Steel browser session? Create a session with `client.sessions.create()`, then call `puppeteer.connect()` with `browserWSEndpoint` set to the session's `websocketUrl` (with your `apiKey` appended) and open a tab with `browser.newPage()`. ### Resources * [Puppeteer documentation](https://pptr.dev) – Official Puppeteer API reference * [Steel Sessions API reference](/api-reference#tag/sessions) – Technical details for managing Steel browser sessions * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Build a Pydantic AI Browser Agent on Steel URL: https://docs.steel.dev/integrations/pydantic-ai [Pydantic AI](https://ai.pydantic.dev/) is the Pydantic team's [agent framework](/cookbook/topics/agents). It's provider-agnostic and reuses the Pydantic models you'd already validate API I/O with for tool arguments and final outputs, so adding an agent to a typed Python codebase doesn't introduce a parallel schema layer. The Steel integration passes a Playwright `Page` through `RunContext.deps`, so every tool in an agent run sees the same cloud browser without module globals. ### Requirements * **Steel API Key**: Active Steel subscription * **Model provider key**: OpenAI, Anthropic, Google, or any other Pydantic AI-supported provider * **Python**: 3.10+ ### Connect Steel to Pydantic AI Define a `BrowserDeps` dataclass holding the Steel-backed Playwright `Page`, register tools that read `ctx.deps.page`, and pass `deps=` to `agent.run`: ```python from dataclasses import dataclass from playwright.async_api import Page, async_playwright from pydantic_ai import Agent, RunContext from steel import Steel @dataclass class BrowserDeps: page: Page async def navigate(ctx: RunContext[BrowserDeps], url: str) -> dict: """Navigate to a URL and wait for the page to load.""" await ctx.deps.page.goto(url, wait_until="domcontentloaded") return {"url": ctx.deps.page.url, "title": await ctx.deps.page.title()} agent = Agent( "openai:gpt-5-mini", deps_type=BrowserDeps, tools=[navigate], ) steel = Steel(steel_api_key=STEEL_API_KEY) session = steel.sessions.create() playwright = await async_playwright().start() browser = await playwright.chromium.connect_over_cdp( f"{session.websocket_url}&apiKey={STEEL_API_KEY}" ) page = browser.contexts[0].pages[0] result = await agent.run("Open example.com and report the title.", deps=BrowserDeps(page=page)) ``` Full runnable starter: [Steel + Pydantic AI recipe →](/cookbook/pydantic-ai) ### FAQ ### Do I need to change my existing Pydantic AI code to use Steel? No — Steel enters through dependency injection. You connect Playwright to a Steel session over CDP and pass the resulting `Page` in via `deps=BrowserDeps(page=page)`; your agent, tools, and output models stay the same. ### How do I connect Pydantic AI to a Steel browser session? Create a session with `steel.sessions.create()`, connect via `chromium.connect_over_cdp(f"{session.websocket_url}&apiKey={STEEL_API_KEY}")`, take `browser.contexts[0].pages[0]`, and pass it as `deps=BrowserDeps(page=page)` to `agent.run()`. ### Does Pydantic AI work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — set them on `sessions.create()` (e.g. `use_proxy`, `solve_captcha`, `stealth_config`). The agent only sees a Playwright `Page` through `ctx.deps`, so session options never leak into tool code. ### Resources * [Pydantic AI documentation](https://ai.pydantic.dev/) – Agents, tools, output validators, retries, and Logfire integration * [Steel Sessions API reference](/api-reference) – Programmatic session control for Steel browsers * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # Replit URL: https://docs.steel.dev/integrations/replit Run [Steel browser automation scripts](/cookbook/topics/browser-automation) in Replit's cloud, no local setup. Templates ship for Python and Node.js with Playwright, Puppeteer, and Selenium. A good fit for prototyping, scheduled jobs, and sharing runnable examples. ### Requirements * **Steel API Key**: Any plan; get a free key [here](https://app.steel.dev/settings/api-keys) * **Replit account**: Free tier available * **Languages**: Python and Node.js (full list of supported languages [here](https://replit.com/templates/languages)) ### Starter Templates * [**Steel Puppeteer Starter**](https://replit.com/@steel-dev/steel-puppeteer-starter) – Node.js template using Puppeteer * [**Steel Playwright Starter**](https://replit.com/@steel-dev/steel-playwright-starter) – Node.js template using Playwright * [**Steel Playwright Python Starter**](https://replit.com/@steel-dev/steel-playwright-python-starter) – Python template using Playwright * [**Steel Selenium Starter**](https://replit.com/@steel-dev/steel-selenium-starter) – Python template using Selenium ### Running a template 1. Hit "Remix this Template" to fork the template (requires a free Replit account) 2. Add your `STEEL_API_KEY` to the secrets pane (located under "Tools" on the left hand pane) 3. Hit Run Don't have an API key? Get a free key at [app.steel.dev/settings/api-keys](http://app.steel.dev/settings/api-keys). ### FAQ ### Do I need any local setup to run Steel automation on Replit? No — everything runs in Replit's cloud. Remix a Steel starter template, add your `STEEL_API_KEY` to the secrets pane, and hit Run. ### Where do I put my Steel API key in Replit? Add `STEEL_API_KEY` in the secrets pane, found under "Tools" in the left-hand pane. Any plan works — you can get a free key at app.steel.dev/settings/api-keys. ### What is the Replit integration good for? Prototyping, scheduled jobs, and sharing runnable examples — the templates give you working Steel scripts in Playwright, Puppeteer, or Selenium without configuring a local environment. A free Replit account is enough to remix and run them. ### Resources * [Replit documentation](https://docs.replit.com) – Learn more about Replit's features * [Steel Sessions API overview](/overview/sessions-api/overview) – Learn about Steel's Sessions API * [Steel Discord](https://discord.gg/steel-dev) – Get help from the Steel team # Run Selenium in the Cloud on Steel URL: https://docs.steel.dev/integrations/selenium Selenium speaks the W3C WebDriver protocol over HTTP, not CDP. Steel runs a WebDriver endpoint at `http://connect.steelbrowser.com/selenium`. Point `webdriver.Remote` at it, attach the Steel API key and session ID as headers on every request, and the rest is plain Selenium 4. Sessions for Selenium need `is_selenium=True` on creation — that flag provisions a WebDriver-compatible node. Without it you get a CDP browser that Selenium cannot drive. ### Requirements * **Steel API Key**: Active Steel subscription * **Runtime**: Python 3.10+ * **Package**: `selenium` 4+ ### Connect Steel to Selenium Subclass `RemoteConnection` to inject `steel-api-key` and `session-id` headers on every WebDriver request, then point `webdriver.Remote` at Steel's WebDriver endpoint: ```python import os from selenium import webdriver from selenium.webdriver.remote.remote_connection import RemoteConnection from steel import Steel class SteelRemoteConnection(RemoteConnection): def __init__(self, remote_server_addr: str, session_id: str): super().__init__(remote_server_addr) self._session_id = session_id def get_remote_connection_headers(self, parsed_url, keep_alive=False): headers = super().get_remote_connection_headers(parsed_url, keep_alive) headers["steel-api-key"] = os.environ["STEEL_API_KEY"] headers["session-id"] = self._session_id return headers client = Steel(steel_api_key=STEEL_API_KEY) session = client.sessions.create(is_selenium=True) driver = webdriver.Remote( command_executor=SteelRemoteConnection( remote_server_addr="http://connect.steelbrowser.com/selenium", session_id=session.id, ), options=webdriver.ChromeOptions(), ) ``` Each command is an HTTP round-trip, so prefer `WebDriverWait` with `expected_conditions` over blind `time.sleep` to avoid compounding latency. Full runnable starter: [Steel + Selenium recipe →](/cookbook/selenium) Steel drives [Playwright and Puppeteer](/cookbook/topics/browser-automation) the same way. ### FAQ ### Do I need to change my existing Selenium code to use Steel? Mostly no — your test logic stays plain Selenium 4. The change is in the connection: point `webdriver.Remote` at Steel's WebDriver endpoint and inject the `steel-api-key` and `session-id` headers on every request via a small `RemoteConnection` subclass. ### How do I connect Selenium to a Steel browser session? Steel runs a WebDriver endpoint at `http://connect.steelbrowser.com/selenium`. Create a session with `client.sessions.create(is_selenium=True)`, then pass a `RemoteConnection` subclass that adds `steel-api-key` and `session-id` headers as the `command_executor` for `webdriver.Remote`. ### Does Selenium work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — those are set when you create the session (e.g. `use_proxy`, `solve_captcha`, `stealth_config` on `sessions.create`), so Selenium doesn't need to know about them. Your WebDriver commands run against the session however it was provisioned. ### Why does my session need `is_selenium=True`? Because Selenium speaks the W3C WebDriver protocol over HTTP, not CDP. `is_selenium=True` provisions a WebDriver-compatible node — without it you get a CDP browser that Selenium cannot drive. ### Resources * [Selenium Python documentation](https://selenium-python.readthedocs.io) – Official Python bindings reference * [WebDriver protocol](https://w3c.github.io/webdriver/) – W3C specification * [Steel Sessions API reference](/api-reference#tag/sessions) – Technical details for managing Steel browser sessions * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # StackBlitz / Bolt.new URL: https://docs.steel.dev/integrations/stackblitz-bolt.new Run [Steel browser automation scripts](/cookbook/topics/browser-automation) in StackBlitz directly in your browser, with no local setup or installation. Well-suited for quick prototyping, sharing running examples, and collaborative development. With [Bolt.new](http://bolt.new/), StackBlitz's AI-powered web development agent, you can write and modify Steel scripts in natural language alongside your code. ### Requirements * **Steel API Key**: Any plan; get a free key [here](https://app.steel.dev/settings/api-keys) * **Languages**: JavaScript and TypeScript (Steel templates only; StackBlitz has limited Python support) * **No account required** to run code (only to save changes) ### Starter Templates * [**Steel Puppeteer Starter**](https://stackblitz.com/edit/steel-puppeteer-starter) – Node.js template using Puppeteer * [**Steel Playwright Starter**](https://stackblitz.com/edit/steel-playwright-starter) – Node.js template using Playwright ### Running a template 1. Click on the template link above to open it in StackBlitz 2. Set your `STEEL_API_KEY` in one of two ways: * Export it in the terminal: `export STEEL_API_KEY=your_key_here` * Create a `.env` file and add: `STEEL_API_KEY=your_key_here` 3. Run `npm run` in the terminal to run the script No account is required to run or even edit the templates. You only need to sign in if you want to save your changes. ### AI-powered development with Bolt.new All our StackBlitz templates can be opened in [Bolt.new](http://bolt.new/), an AI-powered web development agent built on StackBlitz's WebContainer technology. With Bolt.new you can: * Use natural language prompts to modify Steel automation scripts * Build full-stack applications around Steel's capabilities * Get AI assistance while developing your browser automation workflows * Deploy your projects with zero configuration Look for the *Open in Bolt.new* button on our templates to get started with AI-assisted development. ### FAQ ### Do I need a StackBlitz account or any installation to run Steel templates? No — the templates run directly in your browser with no local setup, and no account is required to run or even edit them. You only need to sign in if you want to save your changes. ### How do I set my Steel API key in StackBlitz? Two ways: export it in the terminal with `export STEEL_API_KEY=your_key_here`, or create a `.env` file containing `STEEL_API_KEY=your_key_here`. Then run `npm run` in the terminal to execute the script. ### How does Bolt.new fit into the Steel integration? All Steel StackBlitz templates can be opened in Bolt.new, StackBlitz's AI web-development agent built on WebContainer technology. From there you can modify Steel scripts with natural-language prompts, build full-stack apps around Steel, and deploy with zero configuration — look for the "Open in Bolt.new" button on the templates. ### Resources * [StackBlitz documentation](https://developer.stackblitz.com/) – Learn more about StackBlitz's features * [Steel Sessions API overview](/overview/sessions-api/overview) – Learn about Steel's Sessions API * [Steel Discord](https://discord.gg/steel-dev) – Get help from the Steel team # Run Stagehand on Steel Cloud Browsers URL: https://docs.steel.dev/integrations/stagehand Stagehand is an open-source library for writing [browser automations](/cookbook/topics/browser-automation) in natural language using `act`, `extract`, and `observe` calls. The Steel integration drives Stagehand against a Steel cloud session, so you can replace fragile selectors with instructions like "click the login button" or "extract the top 3 stories". Same API in TypeScript or Python. Good fit for research, scraping, and form workflows. ### Requirements * **Steel API Key**: Active Steel subscription * **OpenAI API Key**: Stagehand's default model provider * **Runtime**: Node.js 20+ or Python 3.10+ ### Connect Steel to Stagehand Pass Steel's CDP URL as `localBrowserLaunchOptions.cdpUrl`: ```typescript import { Stagehand } from "@browserbasehq/stagehand"; import Steel from "steel-sdk"; const client = new Steel({ steelAPIKey: STEEL_API_KEY }); const session = await client.sessions.create({}); const stagehand = new Stagehand({ env: "LOCAL", localBrowserLaunchOptions: { cdpUrl: `${session.websocketUrl}&apiKey=${STEEL_API_KEY}`, }, model: { modelName: "openai/gpt-5", apiKey: OPENAI_API_KEY }, }); await stagehand.init(); ``` Full runnable starter: [Steel + Stagehand recipe →](/cookbook/stagehand) ### FAQ ### Do I need to change my existing Stagehand code to use Steel? No — your `act`, `extract`, and `observe` calls stay the same. The only change is constructing `Stagehand` with `env: "LOCAL"` and Steel's CDP URL in `localBrowserLaunchOptions.cdpUrl`. ### How do I connect Stagehand to a Steel browser session? Create a session with `client.sessions.create()`, then set `cdpUrl` inside `localBrowserLaunchOptions` to the session's `websocketUrl` with your `apiKey` appended, and call `stagehand.init()`. ### Does Stagehand work with Steel's proxies, stealth mode, and CAPTCHA solving? Yes — set them when creating the Steel session (e.g. `useProxy`, `solveCaptcha`, `stealthConfig` on `sessions.create`). Stagehand connects over CDP and is unaware of how the session was provisioned. ### Resources * [Stagehand documentation](https://docs.stagehand.dev/first-steps/introduction) – Official documentation for Stagehand * [Steel Sessions API reference](/api-reference#tag/sessions) – Technical details for managing Steel browser sessions * [Steel Discord](https://discord.gg/steel-dev) – Get help and share what you build # x402 URL: https://docs.steel.dev/integrations/x402 The x402 integration lets you call [Steel's web actions](/cookbook/topics/steel-apis) — scrape, screenshot, and PDF — and pay per request with USDC on Base or Solana. It's built on the [x402 protocol](https://www.x402.org/), so there are no API keys or accounts: you pay for each call with your wallet. **Endpoint:** `https://x402.steel.dev` ### How it works 1. **Send a request** to one of the endpoints below. The server responds with `402 Payment Required` and the payment details (amount, networks, and recipient). 2. **Sign a payment authorization** for the requested amount with your wallet. An x402 client library does this for you. 3. **Resend the request** with the signed `X-PAYMENT` header. You receive your data with a `200 OK` response. ### Available endpoints All endpoints take a `POST` with a JSON body and return JSON. | Endpoint | What it does | |-----------------------|------------------------------------------------------------------------------| | `POST /v1/scrape` | Fetch a rendered page as HTML, Markdown, or readable text — optionally with a screenshot or PDF | | `POST /v1/screenshot` | Capture a screenshot of a page | | `POST /v1/pdf` | Render a page to PDF | #### Request parameters | Parameter | Type | Endpoints | Description | |--------------|------------|---------------|--------------------------------------------------------------------------| | `url` | `string` | all | URL of the page to load. **Required.** | | `format` | `string[]` | scrape | Output format(s): `html`, `readability`, `cleaned_html`, `markdown`. Defaults to `html`. | | `screenshot` | `boolean` | scrape | Include a screenshot in the response. | | `pdf` | `boolean` | scrape | Include a PDF in the response. | | `fullPage` | `boolean` | screenshot | Capture the full scrollable page. | | `delay` | `number` | all | Delay before acting, in milliseconds. | | `useProxy` | `boolean` | all | Route through a Steel-provided residential proxy. | | `region` | `string` | all | Region to run the action in. | ### Pricing Each request costs **$0.01 in USDC** (`10000` base units), charged on whichever network you pay from. There's no subscription and no per-hour billing — you pay only for the requests you make. ### Requirements * **Wallet**: Base or Solana wallet with USDC ### Supported tokens and networks | Network | USDC Contract Address | |------------------------|---------------------------------------------------| | Base (mainnet) | **0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913** | | Solana (mainnet) | **EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v** | ### Quickstart First, see the payment requirements by sending an unpaid request: ```bash curl -i -X POST https://x402.steel.dev/v1/scrape \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com", "format": ["markdown"]}' ``` You'll get a `402 Payment Required` describing the amount and the Base and Solana payment options. To complete the call, use an x402 client library — it reads the `402`, signs the payment, and retries automatically. For example, with [`x402-fetch`](https://www.x402.org/): ```ts import { wrapFetchWithPayment } from "x402-fetch"; import { privateKeyToAccount } from "viem/accounts"; const account = privateKeyToAccount(process.env.PRIVATE_KEY); const fetchWithPay = wrapFetchWithPayment(fetch, account); const res = await fetchWithPay("https://x402.steel.dev/v1/scrape", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ url: "https://example.com", format: ["markdown"] }), }); const data = await res.json(); ``` ### FAQ ### Do I need a Steel account or API key to use x402? No — x402 is pay-per-use with cryptocurrency. You call the scrape, screenshot, and PDF endpoints by paying with USDC on Base or Solana, with no API keys or accounts required. ### How do I make a request over x402? Send a `POST` to an endpoint like `https://x402.steel.dev/v1/scrape`; the server responds with `402 Payment Required`. Sign a payment authorization for the requested amount with your wallet (an x402 client does this for you), resend the request with the signed `X-PAYMENT` header, and you get your data with a `200 OK`. ### How much does it cost? $0.01 in USDC per request, paid on Base or Solana. All you need is a wallet holding USDC. ### Resources * [x402 protocol](https://www.x402.org/) – Learn more about the x402 protocol * [Steel API reference](/api-reference) – Full reference for the scrape, screenshot, and PDF endpoints * [Steel Discord](https://discord.gg/steel-dev) – Get help and share your implementations # Authentication URL: https://docs.steel.dev/overview/authentication Every request to Steel is authenticated with an API key tied to your organization. This page covers how to get a key, how to use it with the REST API, SDKs, and WebSocket connections, and how to manage and rotate keys over time. ### Overview Steel uses API key authentication. Once you've created a key in the dashboard, you pass it to Steel one of three ways depending on the interface you're using: - **REST API**: as the `steel-api-key` HTTP header - **SDKs (Node.js / Python)**: as a client option, or via the `STEEL_API_KEY` environment variable - **Browser connections (CDP over WebSocket)**: as the `apiKey` query parameter on `wss://connect.steel.dev` A single key grants access to your entire organization's Steel resources: sessions, files, credentials, profiles, and everything else. Treat it like a password. ### Getting Your API Key 1. Sign in at [app.steel.dev](https://app.steel.dev). 2. Open **Settings → API Keys** ([direct link](https://app.steel.dev/settings/api-keys)). 3. Click **Create API Key**, give it a descriptive name (e.g. `production`, `local-dev`, `ci`), and copy the value. You can also provision a Steel project and `STEEL_API_KEY` from the Stripe CLI with [`stripe projects add steel/browser`](/overview/stripe-projects). ### Save your key somewhere safe The full key is only shown once at the moment of creation. If you lose it, you'll need to delete the key and create a new one. ### Setting Up Environment Variables Both SDKs and most example code in these docs assume your key is available as the `STEEL_API_KEY` environment variable. The easiest setup is a `.env` file in your project root: ```bash STEEL_API_KEY=ste-your-api-key-here ``` Make sure `.env` is listed in your `.gitignore` so the key never lands in version control. ### Using the API Key #### SDKs If `STEEL_API_KEY` is set in your environment, the official SDKs will pick it up automatically. You don't need to pass anything explicitly. ```typescript import Steel from 'steel-sdk'; // Reads STEEL_API_KEY from the environment const client = new Steel(); const session = await client.sessions.create(); ``` ```python from steel import Steel # Reads STEEL_API_KEY from the environment client = Steel() session = client.sessions.create() ``` You can also pass the key explicitly, which is useful when you manage multiple keys or fetch the value from a secrets manager at runtime: ```typescript import Steel from "steel-sdk"; const client = new Steel({ steelAPIKey: process.env.STEEL_API_KEY, }); ``` ```python import os from steel import Steel client = Steel( steel_api_key=os.environ["STEEL_API_KEY"], ) ``` #### REST API When calling the REST API directly, send your key in the `steel-api-key` header. ```bash curl https://api.steel.dev/v1/sessions \ -H "steel-api-key: $STEEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` The same header works for every authenticated endpoint: sessions, files, credentials, profiles, extensions, and so on. See the [API Reference](/api-reference) for the full list. #### Browser Connections (CDP over WebSocket) When connecting an automation framework (Playwright, Puppeteer, Selenium) to a live Steel session over the Chrome DevTools Protocol, pass your key as the `apiKey` query parameter on the `wss://connect.steel.dev` endpoint: ```typescript import { chromium } from "playwright"; const browser = await chromium.connectOverCDP( `wss://connect.steel.dev?apiKey=${process.env.STEEL_API_KEY}&sessionId=${session.id}`, ); ``` ```python import os from playwright.sync_api import sync_playwright playwright = sync_playwright().start() browser = playwright.chromium.connect_over_cdp( f"wss://connect.steel.dev?apiKey={os.environ['STEEL_API_KEY']}&sessionId={session.id}" ) ``` The `sessionId` parameter is optional: if omitted, Steel will start a new session with default settings and connect you to it. See the framework-specific guides for full examples: [Puppeteer](/cookbook/puppeteer), [Playwright](/cookbook/playwright), [Playwright (Python)](/cookbook/playwright-python), [Selenium](/cookbook/selenium). #### Steel CLI The [Steel CLI](/overview/steel-cli) authenticates with the same keys. The easiest way is: ```bash steel login ``` This walks you through signing in and stores a key locally. Alternatively, set `STEEL_API_KEY` in your environment and the CLI will use it directly: useful for CI and non-interactive environments. ### Managing Your API Keys All key management happens in the [API Keys dashboard](https://app.steel.dev/settings/api-keys). From there you can: - **Create** a new key: pick a clear name so you can later identify where it's being used. - **View** the list of existing keys, when they were created, and when they were last used. - **Delete** a key: this immediately revokes it. Any service still using that key will start receiving `401 Unauthorized` responses. Steel does not currently expose key management through the public API: keys are only created and deleted through the dashboard. #### Rotating Keys To rotate a key without downtime: 1. Create a new API key in the dashboard. 2. Roll the new key out to all the places that use it (environment variables, secret managers, CI, etc.). 3. Verify traffic is flowing under the new key (the "Last used" timestamp in the dashboard will update). 4. Delete the old key. We recommend using separate keys per environment (e.g. `production`, `staging`, `local-dev`) so you can rotate them independently and narrow the blast radius of a leak. ### Security Best Practices - **Never commit keys to source control.** Use `.env` files (and `.gitignore` them), your platform's secret manager, or CI secrets. - **Never ship keys in client-side code.** Steel keys are meant for trusted server-side environments. Exposing one in a browser bundle, mobile app, or public repo effectively makes it public. - **Scope keys per environment.** One key per environment (prod, staging, dev) makes incidents easier to contain. - **Rotate on suspicion.** If a key might have been exposed (in logs, a screenshare, a repo, a CI job), delete it and create a new one immediately. - **Use the `name` field.** Naming your keys when you create them makes it much easier to audit and revoke the right one later. ### Troubleshooting If Steel rejects your request, you'll get an HTTP `401 Unauthorized` with a short message explaining why: - **`Invalid Steel API Key`**: the key you sent doesn't match any active key on your account. Double-check it for typos, trailing whitespace, or the wrong environment variable. If you recently deleted the key, it will no longer work. - **`Missing API key`**: no `steel-api-key` header was sent. Make sure your SDK client was initialized with a key, or that the header is present on your raw HTTP request. - **`Account suspended`** (`403 Forbidden`): your organization has been blocked. Reach out to [team@steel.dev](mailto:team@steel.dev?subject=Account%20Suspension) to resolve this. A quick way to sanity-check a key is to hit the sessions endpoint: ```bash curl -i https://api.steel.dev/v1/sessions \ -H "steel-api-key: $STEEL_API_KEY" ``` A `200 OK` means you're authenticated. A `401` means the key is wrong or missing. ### Stuck on auth? Ping us in the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section, or email [team@steel.dev](mailto:team@steel.dev?subject=Authentication%20Help). ### FAQ ### How do I authenticate requests to the Steel API? Every request uses an API key tied to your organization. Pass it as the `steel-api-key` HTTP header for the REST API, via the `STEEL_API_KEY` environment variable (or client option) for the SDKs, or as the `apiKey` query parameter on `wss://connect.steel.dev` for CDP browser connections. ### Where do I get a Steel API key? Sign in at app.steel.dev, open Settings → API Keys, click Create API Key, and copy the value. The full key is shown only once at creation, so save it somewhere safe; if you lose it you must delete it and create a new one. ### Why am I getting a 401 Unauthorized from Steel? A 401 means your key is invalid (typo, trailing whitespace, wrong env var, or recently deleted) or missing (`Missing API key` means no `steel-api-key` header was sent). A quick sanity check is `curl -i https://api.steel.dev/v1/sessions` with your key header: 200 means authenticated. # Intro to Steel URL: https://docs.steel.dev/overview/intro-to-steel ### **Getting LLMs to use the web is _hard_** We want AI products that can book us a flight, find us a sublet, buy us a prom suit, and get us an interview. But if you’ve ever tried to build an AI app that can interact with the web today, you know the headaches: * **Dynamic Content:** Modern sites heavily rely on client-side rendering and lazy loading, requiring scrapers to wait for page hydration and execute JS to access the full content. * **Complex Navigation:** Reaching desired data often involves multi-step flows, simulating user actions like clicks, typing, and handling CAPTCHAs. * **Authentication:** High-value data and functionality frequently sits behind auth walls, necessitating robust identity management and auto-login capabilities. * **Infrastructure Overhead:** Efficiently scaling and managing headless browser fleets is complex, with issues like cold starts, resource contention, and reliability eating up valuable dev cycles. * **Lack of Web APIs:** Many critical sites still lack API access, forcing teams to build and maintain brittle custom scrapers for each target. This is by design. Most of the web is designed to be anti-bot and human friendly. But what if we flipped that? ### **A better way to take your LLMs online** Steel is a headless browser API that lets AI engineers: * Control fleets of browser sessions in the cloud via API or Python/Node SDKs * Easily extract page data as cleaned HTML, markdown, PDFs, or screenshots * Access data behind logins with persistent cookies and automatic sign-in * Render complex client-side content with JavaScript execution * Bypass anti-bot measures with rotating proxies, stealth configs, and CAPTCHA solving * Reduce token usage and costs by up to 80% with optimized page formats * Reuse session and cookie data across multiple runs * Debug with ease using live session viewers, replays, and embeddings All fully managed, and ready to scale, so you can focus on building shipping product, not babysitting browsers. Under the hood, Steel’s cloud-native platform handles all the headaches of browser infrastructure: * Executing JavaScript to load and hydrate pages * Managing credentials, sign-in flows, proxies, CAPTCHAs, and cookies * Horizontal browser scaling and recovering from failures * Optimizing data formats to reduce LLM token usage ### Get started with Sessions API - [Overview](/overview/sessions-api/overview) - [Quickstart](/overview/sessions-api/quickstart) - [Connect with Puppeteer](/cookbook/puppeteer) - [Connect with Playwright](/cookbook/playwright) - [Connect with Selenium](/cookbook/selenium) ### Reference - [API Reference](/api-reference) - [Python SDK Reference](/steel-python-sdk) - [Node SDK Reference](/steel-js-sdk) ### FAQ ### What is Steel and what does it do? Steel is an open-source browser API purpose-built for AI agents. It lets you control fleets of browser sessions in the cloud via API or Python/Node SDKs, handling JavaScript rendering, logins, proxies, CAPTCHAs, and scaling so you can focus on shipping product instead of babysitting browsers. ### Why is it so hard for AI agents to browse the web? Modern sites rely on client-side rendering, multi-step navigation, CAPTCHAs, and auth walls, and many critical sites lack APIs entirely. Most of the web is deliberately anti-bot and human-friendly, which forces teams to build brittle custom scrapers and manage headless browser fleets themselves. ### Can Steel bypass anti-bot measures and CAPTCHAs? Yes. Steel lets you bypass anti-bot measures with rotating proxies, stealth configs, and CAPTCHA solving, and it can access data behind logins using persistent cookies and automatic sign-in. ### Does Steel help reduce LLM token costs? Yes. Steel can reduce token usage and costs by up to 80% with optimized page formats, extracting page data as cleaned HTML, markdown, PDFs, or screenshots instead of raw pages. # Legal URL: https://docs.steel.dev/overview/legal Please visit our latest [Terms of Service](https://docs.google.com/document/d/1VuaLxBq150cR9vyiir9B4GUsvqSu0Rd64Vtu-HiSqp8/edit?tab=t.0#heading=h.nf9mun4iq7m9) Please visit our latest [Privacy Policy](https://docs.google.com/document/d/1q3QBkFm4ke-_oqEO3wyP5yi64TazRBt6wbvIE_Zx69A/edit?usp=sharing) # Need Help? URL: https://docs.steel.dev/overview/need-help - [Overview](/) - [Changelog](/changelog) - [API Reference](/api-reference) - [Cookbook](https://github.com/steel-dev/steel-cookbook/) - [Discord](https://discord.gg/steel-dev) - [Github](https://github.com/steel-dev) - [Dashboard](https://app.steel.dev/) We’re here to support in any way we can! You can connect with us on: - [Discord](https://discord.gg/steel-dev) - [GitHub](https://github.com/steel-dev) or send an email to our team support at [team@steel.dev](mailto:team@steel.dev?subject=Steel%20Support%20Issue) # Pricing/Limits URL: https://docs.steel.dev/overview/pricinglimits **Last Edit:** June 30th, 2026 ### Pricing Table | Tier | Price | Included usage | | ---------- | -------------- | ----------------------------------------- | | Launch | $0 + usage | $30 free usage credits, one time | | Scale | $250 + usage | $100 free usage credits / month | | Enterprise | Custom + usage | [Talk to the founders](https://cal.com/hussien-hussien-fjxt3x/intro-chat-w-steel-founders) | | Category | Feature | Launch | Scale | Enterprise | | --- | --- | --- | --- | --- | | Rates | Browser hours | $0.10/hour | $0.08/hour | Custom | | Rates | Proxy bandwidth | $10/GB | $6/GB | Custom | | Rates | Captcha solves | $3/1k | $1/1k | Custom | | Rates | Browser tools (`/scrape`, `/screenshot`, `/pdf`) | $5/1k | $5/1k | Custom | | Features | Concurrent browser sessions | 10 | 100 | 1,000+ | | Features | Stealth Browser | - | - | Included | | Features | Dedicated IPs | - | $5/IP/month | Custom | | Features | Max session time | 15 minutes | 1 hour | Up to 24 hours | | Features | Number of seats | Up to 3 | Unlimited | Unlimited | | Features | Reserved browser pools | - | - | Included | | Limits | Requests per minute | 60 | 600 | Custom | | Limits | Data retention | 7 days | 14 days | Custom | | Support | Email support | Included | Included | Included | | Support | Community support | Included | Included | Included | | Support | Dedicated Slack channel | - | Included | Included | | Support | 911 email | - | - | Included | | Support | Support & uptime SLAs | - | - | Included | | Security | Enterprise SSO | - | Included | Included | | Security | HIPAA-ready BAA | - | Included | Included | \* Browser hours are billed by the minute, rounded up. ### How Credits Work Usage credits are applied to metered Steel usage, including browser hours, proxy bandwidth, captcha solves, and Browser Tools usage. Launch includes $30 in one-time free usage credits, valid for 90 days. Scale includes $100 in free usage credits each month. Usage beyond included credits is billed at your plan's listed rates. Enterprise pricing, usage credits, and limits are customized for your workload. You can monitor usage by meter in the dashboard, including session time, proxy bandwidth, captcha solves, and remaining balance. You can also top up credits or enable auto top-up so a run does not stop because the workspace runs out of balance. ### Verify your Launch account with a $10 deposit To use CAPTCHA solving or Steel-provided proxies on Launch, verify your account by adding $10 in paid balance. Free credits do not count. The deposit goes toward usage, not an extra fee. Scale includes anti-bot; Enterprise is custom. ### Usage Examples If you spent your included credits on a single usage category, you would get roughly: #### Launch * 300 browser hours * 3GB proxy bandwidth * 10,000 captcha solves * 6,000 Browser Tools calls #### Scale * 1,250 browser hours * 16.7GB proxy bandwidth * 100,000 captcha solves * 20,000 Browser Tools calls \* In practice, most workloads use a mix of browser hours, proxies, captcha solves, and Browser Tools calls. **_Enterprise plans offer custom pricing, limits, and infrastructure for high-volume or specialized workloads._** ### Need custom pricing or limits? Talk to the founders about Enterprise pricing, reserved browser pools, custom limits, and support requirements. [Schedule a call](https://cal.com/hussien-hussien-fjxt3x/intro-chat-w-steel-founders) ### FAQ ### How much does Steel cost? Steel has a Launch plan at $0 + usage with $30 in one-time free usage credits valid for 90 days, a Scale plan at $250 + usage with $100 in monthly free usage credits, and custom Enterprise pricing. ### How long can a Steel browser session stay alive? Launch sessions can run up to 15 minutes, Scale sessions can run up to 1 hour, and Enterprise sessions can run up to 24 hours. ### How many concurrent browser sessions can I run on Steel? Launch includes 10 concurrent browser sessions, Scale includes 100 concurrent browser sessions, and Enterprise supports 1,000+ concurrent browser sessions. ### How is Steel browser time billed? Browser hours are billed by the minute, rounded up. Launch is $0.10/hour, Scale is $0.08/hour, and Enterprise is custom. ### How much do proxies cost? Proxy bandwidth is $10/GB on Launch and $6/GB on Scale, with custom Enterprise pricing. ### How much do captcha solves cost? Captcha solves are $3 per 1,000 solves on Launch and $1 per 1,000 solves on Scale, with custom Enterprise pricing. ### How do I enable CAPTCHA solving on Launch? Verify your Launch account by adding $10 in paid balance. This enables CAPTCHA solving and Steel-provided proxies. Free credits do not count. The deposit goes toward usage, not an extra fee. Scale includes anti-bot; Enterprise is custom. ### How much do Browser Tools cost? Browser Tools usage for `/scrape`, `/screenshot`, and `/pdf` is $5 per 1,000 calls on Launch and Scale, with custom Enterprise pricing. ### How much do Dedicated IPs cost? Dedicated IPs are available on Scale for $5 per IP per month. Enterprise Dedicated IP pricing is custom. ### What happens if I am already on a legacy plan? Existing Starter, Developer, and Startup customers can keep their legacy plan in the dashboard and switch when they choose. # Steel CLI URL: https://docs.steel.dev/overview/steel-cli ## Overview The Steel CLI lets you run full browser workflows from the terminal, end-to-end. You can start a browser session, navigate pages, click/fill/type, extract content, and stop the session without wiring custom browser infrastructure. What it enables: - Run browser automation in cloud mode (default) or self-hosted/local mode - Drive pages with terminal-first browser commands (`open`, `snapshot`, `fill`, `click`, etc.) - Use API tools for `scrape`, `screenshot`, and `pdf` - Bootstrap projects quickly with `forge` and run templates instantly with `run` Under the hood, `steel browser` is directly integrated with the `agent-browser` runtime. That means Steel adds session lifecycle, auth, and endpoint routing while preserving familiar browser command behavior. - GitHub: [steel-dev/cli](https://github.com/steel-dev/cli) ## Documentation Index (for Agents) If you are using an AI agent and want a complete docs index before exploring pages: - `https://docs.steel.dev/llms-full.txt` This returns a flattened, agent-friendly text map of the docs site. ## Installation Install with the official script (recommended): ```bash curl -fsS https://setup.steel.dev | sh ``` This installs the native `steel` binary to `~/.steel/bin` and runs `steel init` to log you in, verify connectivity, and install coding-agent skills. ## Quick Start ### Cloud Mode (Default) ```bash steel login steel browser start --session my-job steel browser open https://example.com --session my-job steel browser snapshot -i --session my-job steel browser stop --session my-job ``` ### Self-Hosted Endpoint ```bash steel browser start --api-url https://steel.your-domain.dev/v1 --session my-job steel browser open https://example.com --api-url https://steel.your-domain.dev/v1 --session my-job ``` ### Local Runtime (`localhost`) Flow ```bash steel dev install steel dev start steel browser start --local --session local-job steel browser open https://example.com --session local-job steel browser stop --session local-job steel dev stop ``` ## Skills for Coding Agents Steel ships a first-party skills catalog for agent workflows: - [Steel Skills](/overview/skills) - [steel-dev/skills](https://github.com/steel-dev/skills) This is designed for coding agents, including: - Codex - OpenCode - OpenClaw - Claude Code Install from the public skills catalog: ```bash npx skills add steel-dev/skills --skill steel-browser ``` Or through the Steel CLI helper: ```bash steel skills install steel-browser steel skills list steel skills doctor ``` After installation, restart your agent client so it can discover newly installed skills. What this skill gives agents: - Mode-aware command planning (cloud vs self-hosted) - Named-session lifecycle discipline (`start -> work -> stop`) - Reliable command patterns for `steel browser` passthrough actions - Migration guidance from `agent-browser` - Troubleshooting playbooks for auth/session/CAPTCHA failures ### Typical Agent Skill Workflow Most agent loops follow this pattern: 1. Start or attach a named session. 2. Open a page and inspect interactable elements (`snapshot -i`). 3. Perform actions (`fill`, `select`, `check`, `click`). 4. Wait for the post-action state and verify output. 5. Stop the session when done. ```bash SESSION="signup-demo-$(date +%s)" steel browser start --session "$SESSION" steel browser open https://example.com/signup --session "$SESSION" steel browser snapshot -i --session "$SESSION" steel browser fill @e1 "Jane Doe" --session "$SESSION" steel browser fill @e2 "jane@example.com" --session "$SESSION" steel browser select @e3 "California" --session "$SESSION" steel browser check @e4 --session "$SESSION" steel browser click @e5 --session "$SESSION" steel browser wait --load networkidle --session "$SESSION" steel browser stop --session "$SESSION" ``` If you already know upstream `agent-browser`, the behavior is typically command-prefix only: ```bash agent-browser open https://example.com/signup agent-browser snapshot -i agent-browser fill @e1 "Jane Doe" agent-browser fill @e2 "jane@example.com" agent-browser select @e3 "California" agent-browser check @e4 agent-browser click @e5 agent-browser wait --load networkidle ``` ## Command Model ### Steel-Owned Browser Lifecycle Commands - `steel browser start` - `steel browser stop` - `steel browser sessions` - `steel browser live` - `steel browser captcha solve` ### Inherited Browser Commands (Passthrough) All non-lifecycle `steel browser ` calls are routed through the vendored `agent-browser` runtime. Migration is usually command-prefix only: - Before: `agent-browser ...` - After: `steel browser ...` ### Essential Inherited Commands These are the most common inherited commands agents use: - Page navigation: `open`, `back`, `forward`, `reload` - Page understanding: `snapshot`, `snapshot -i` - Interaction: `click`, `fill`, `type`, `select`, `check`, `press`, `hover` - Data retrieval: `get text`, `get html`, `get title`, `get url` - Synchronization: `wait`, `wait --load networkidle`, `wait --text` - Debugging: `screenshot`, `errors`, `console` Use command help directly when needed: ```bash steel browser --help steel browser click --help steel browser wait --help ``` For full command references: - [Steel browser commands reference](https://github.com/steel-dev/cli/blob/main/docs/references/steel-browser-commands.md) - [Steel browser session lifecycle reference](https://github.com/steel-dev/cli/blob/main/docs/references/steel-browser.md) ## Command Overview | Group | Commands | | ------------------- | -------------------------------------------------------------------------------------------- | | Onboarding | `init`, `forge` | | Browser lifecycle | `browser start`, `browser stop`, `browser sessions`, `browser live`, `browser captcha solve` | | Browser passthrough | `steel browser ` | | API tools | `scrape`, `screenshot`, `pdf` | | Local runtime | `dev install`, `dev start`, `dev stop` | | Profiles | `profile import`, `profile sync`, `profile list`, `profile delete` | | Credentials | `credentials list`, `credentials create`, `credentials update`, `credentials delete` | | Account + utility | `login`, `logout`, `config`, `doctor`, `cache`, `update` | ## Common Workflows ### 1. Named Session Lifecycle ```bash SESSION="job-$(date +%s)" steel browser start --session "$SESSION" steel browser open https://example.com --session "$SESSION" steel browser snapshot -i --session "$SESSION" steel browser get title --session "$SESSION" steel browser stop --session "$SESSION" ``` ### 2. CAPTCHA-Aware Sessions ```bash # Manual solve mode steel browser start --session my-job --session-solve-captcha steel browser captcha solve --session my-job # Auto solve mode (stealth preset) steel browser start --session my-job --stealth ``` ### 3. `agent-browser` Migration ```bash # Before agent-browser open https://example.com agent-browser snapshot -i agent-browser click @e3 # After steel browser open https://example.com steel browser snapshot -i steel browser click @e3 ``` ### 4. API Tool Commands ```bash # Scrape (markdown-first output by default) steel scrape https://example.com # Screenshot steel screenshot https://example.com --full-page # PDF steel pdf https://example.com ``` ## `forge` (Templates) Use `forge` to scaffold a project from a template. ```bash # Scaffold a project steel forge playwright --name my-bot ``` List all templates and flags: ```bash steel forge --help ``` ## Endpoint Resolution For browser lifecycle, passthrough bootstrap, and API tools (`scrape`, `screenshot`, `pdf`), endpoint selection is deterministic. Self-hosted precedence: 1. `--api-url ` 2. `STEEL_BROWSER_API_URL` 3. `STEEL_LOCAL_API_URL` 4. `browser.apiUrl` in `~/.config/steel/config.json` 5. `http://localhost:3000/v1` Cloud precedence: 1. `STEEL_API_URL` 2. `https://api.steel.dev/v1` Attach-flag override: - If `--cdp` or `--auto-connect` is provided, Steel skips bootstrap injection and forwards passthrough arguments unchanged. ## Auth, Config, and Updates If you provision Steel through Stripe Projects, `stripe projects add steel/browser` writes a standard `STEEL_API_KEY` that the Steel CLI can read from your environment. See [Stripe Projects](/overview/stripe-projects). ```bash steel login steel config steel logout steel cache --clean steel update steel update --check steel update --force ``` Disable auto-update checks (24-hour cache window): ```bash steel scrape https://example.com --no-update-check STEEL_CLI_SKIP_UPDATE_CHECK=true steel scrape https://example.com CI=true steel scrape https://example.com NODE_ENV=test steel scrape https://example.com ``` ## Runtime and Output Notes - `steel scrape` defaults to markdown-first output; use `--raw` for full JSON payload. - `steel browser start` and `steel browser sessions` return display-safe `connect_url` values with sensitive query parameters redacted. - Browser command paths bypass auto-update checks to reduce interactive latency. ## Troubleshooting - `Missing browser auth...`: run `steel login` or set `STEEL_API_KEY`. - `Failed to reach Steel session API ...`: confirm mode and endpoint settings (`--local`, `--api-url`, env vars). - Session reuse issues: use a consistent `--session ` across every step. - Local runtime issues: run `steel dev install` once, then `steel dev start`. - Stale state: run `steel browser stop --all` and start a fresh named session. ## References - [Steel CLI README](https://github.com/steel-dev/cli/blob/main/README.md) - [Generated CLI Reference](https://github.com/steel-dev/cli/blob/main/docs/cli-reference.md) - [Steel Browser Reference](https://github.com/steel-dev/cli/blob/main/docs/references/steel-browser.md) - [Steel Skills](/overview/skills) ### FAQ ### How do I install the Steel CLI? Run `curl -fsS https://setup.steel.dev | sh`. This installs the native `steel` binary to `~/.steel/bin` and runs `steel init` to log you in, verify connectivity, and install coding-agent skills. ### Can I scrape or screenshot a page from the terminal without writing code? Yes. The CLI ships one-shot API tools: `steel scrape ` (markdown-first output by default, `--raw` for full JSON), `steel screenshot --full-page`, and `steel pdf `. # Stripe Projects URL: https://docs.steel.dev/overview/stripe-projects Steel is available through [Stripe Projects](https://docs.stripe.com/projects), a Stripe CLI workflow for provisioning third-party services and syncing credentials into your project. Add Steel with `stripe projects add steel/browser` to create a Steel project and project-scoped `STEEL_API_KEY` for cloud browser sessions. ## Overview Stripe Projects provisions provider resources from the terminal and writes credentials into your active environment file. For Steel, the provisioned resource is a Steel project plus an API key scoped to that project. | Command | What it does | | --- | --- | | `stripe projects init` | Initializes a Stripe Projects workspace in your app directory. | | `stripe projects add steel/browser` | Provisions a Steel project and syncs credentials into `.env`. | After provisioning, your app uses the standard Steel API, SDKs, and authentication model. See [authentication](/overview/authentication) and the [Steel CLI](/overview/steel-cli). ## Prerequisites Install the [Stripe CLI](https://docs.stripe.com/stripe-cli/install), then install the Projects plugin: ```bash stripe plugin install projects ``` ## Provision Steel Initialize Stripe Projects in your app directory, then add Steel: ```bash stripe projects init my-app stripe projects add steel/browser ``` The add command links your Stripe account to a Steel account, creating one when needed, then provisions a Steel project and API key inside the Steel account you own. Stripe Projects syncs the returned credentials into your active environment output file, `.env` by default. ## What lands in `.env` Steel returns a project-scoped API key plus resource metadata to Stripe Projects. The key your app uses directly is: ```bash STEEL_API_KEY=ste-... ``` Use `stripe projects env` to list synced variable names with values redacted: ```bash stripe projects env ``` Keep `.env` out of version control. `stripe projects init` adds credential files to `.gitignore`, but review your repository before committing. ## Use the credentials The Steel SDK reads `STEEL_API_KEY` from the environment automatically: ```typescript import Steel from 'steel-sdk'; const client = new Steel(); const session = await client.sessions.create(); ``` ```python from steel import Steel client = Steel() session = client.sessions.create() ``` ## Plans and pricing Steel is available through Stripe Projects on Launch and Scale plans. Current plan limits, included credits, billing requirements, and metered rates live on [pricing and limits](/overview/pricinglimits). Upgrade between available Steel plan tiers from the Stripe CLI: ```bash stripe projects upgrade steel/browser ``` ## Pull credentials on another machine If you cloned the repo or a teammate provisioned Steel, pull the current credentials into your local environment file: ```bash stripe projects env --pull ``` ## Limits and self-hosting The `steel-browser` runtime is open source under Apache-2.0, so teams can inspect the code and run it locally or self-hosted when they need a local path. Managed Steel Cloud features still require Steel Cloud. | Ships with the open-source runtime | Steel Cloud only | | --- | --- | | Browser automation core | Managed residential proxies | | Session lifecycle and tracing | Credentials API | | Local and self-hosted deployment | Higher concurrency and managed anti-bot features | For plan limits such as concurrent sessions, session length, requests per minute, and data retention, see [pricing and limits](/overview/pricinglimits). ### FAQ ### Do I need a Steel account before I run `stripe projects add`? No. The command links your Stripe account to a Steel account, creating one when needed. The Steel project and `STEEL_API_KEY` land in a Steel account you own. ### Where do my provisioned resources live? In your own Steel account. `stripe projects add steel/browser` provisions a Steel project plus a project-scoped API key inside the Steel organization tied to your Stripe account. ### Can I link an existing Steel project to a Stripe Project? Not today. Steel provisions a fresh project for each Stripe Project rather than attaching an existing Steel project. ### Do the provisioned credentials work with the Steel SDK and CLI? Yes. Provisioning writes a standard `STEEL_API_KEY`, so the official SDKs, the REST API, and the Steel CLI can use it from the environment. # Agents URL: https://docs.steel.dev/cookbook/topics/agents - [Run a durable browser agent with Restate](/cookbook/restate-agent): Build a Restate Virtual Object in TypeScript that uses durable OpenAI planning steps and Steel scraping to answer browser research questions. - [Expose a Steel browser to any MCP client](/cookbook/mcp): Build a Model Context Protocol server in Go with the official SDK and chromedp that hands any MCP client a Steel cloud browser through explicit session-handle tools. - [Build a browser agent with Genkit](/cookbook/genkit): Use Steel with Genkit Go to build a tool-calling agent that navigates and extracts from a chromedp-backed browser and completes a web task. - [Build a browser agent with Eino](/cookbook/eino): Use Steel with the ByteDance Eino framework to build a ReAct agent that calls Steel's scrape API as a tool to research and answer a web question. - [Build a browser agent with rig](/cookbook/rig): Use Steel with rig to build an agent that drives a cloud browser over CDP with chromiumoxide through navigate and extract tools, then answers a multi-step web task. - [Build a research agent with Swiftide](/cookbook/swiftide): Use Steel with Swiftide to build an agent whose tool reads the web through Steel's scrape endpoint, so the model works from clean Markdown with no browser library. - [Build a browser agent with LangChainGo](/cookbook/langchaingo): Use Steel with LangChainGo's zero-shot ReAct (MRKL) agent and a string-in, string-out scrape tool so Claude reads a page and answers a question. - [Build a browser agent with Google ADK](/cookbook/google-adk): Use Steel with Google's Agent Development Kit (ADK) for Go to build a tool-using browser agent that drives a chromedp session over CDP and reads Hacker News. - [Build a browser agent with Microsoft Agent Framework](/cookbook/microsoft-agent-framework): Use Steel with Microsoft Agent Framework 1.0 (the successor to AutoGen and Semantic Kernel) to build a tool-using browser agent. - [Chat with any webpage on Convex](/cookbook/convex-chat-with-page): Convex app that streams an AI agent's answer about any URL. The agent runs server-side with one Steel-backed scrape tool and pages through long articles via a chunked cache. - [Deep research with Claude Agent SDK subagents](/cookbook/deep-research): Lead orchestrator dispatches parallel researcher subagents, each driving its own Steel browser, and synthesizes findings into a cited Markdown report. - [Combine You.com search with Steel browser actions](/cookbook/you-com-search): Pair the You.com Search and Contents APIs with a Steel cloud browser in a search-then-act LangChain agent that prefers the cheap path and only opens a session when interaction is required. - [Build a browser agent with the Claude Agent SDK](/cookbook/claude-agent-sdk): Use Steel with the Claude Agent SDK (TypeScript) to build a tool-using browser agent on Anthropic's first-party agent loop. - [Build a typed browser agent with Pydantic AI](/cookbook/pydantic-ai): Use Steel with Pydantic AI to build typed, provider-agnostic browser agents with dependency injection. - [Build a typed browser agent with LangGraph](/cookbook/langgraph): Use Steel with LangGraph to build a typed browser agent with an explicit state-machine loop and a structured-output formatter node. - [Build a typed browser agent with Mastra](/cookbook/mastra): Use Steel with Mastra to build a typed browser agent with the Mastra Model Router and Studio playground. - [Build a typed browser agent with the OpenAI Agents SDK](/cookbook/openai-agents): Use Steel with the OpenAI Agents SDK for TypeScript to build typed, tool-using browser agents. - [Build a typed browser agent with the Vercel AI SDK](/cookbook/vercel-ai-sdk): Use Steel with the Vercel AI SDK v6 ToolLoopAgent for typed, tool-using browser agents. - [Stream a browser agent into a Next.js chat app](/cookbook/vercel-ai-sdk-nextjs): A Next.js App Router chat app where a Vercel AI SDK agent drives a Steel cloud browser with embedded Live View. - [Solve reCAPTCHA v2 manually with Browser Use](/cookbook/browser-use-captcha-manual): Manually solve reCAPTCHA v2 using Steel's CAPTCHA API with the browser-use framework. - [Build a multi-agent browser workflow with CrewAI](/cookbook/crewai): Integrate Steel with the CrewAI multi-agent framework. - [Build a browser agent with Inngest AgentKit](/cookbook/agentkit): Integrate Steel with Inngest's AgentKit framework. - [Build a browser agent with Agno](/cookbook/agno): Integrate Steel with the Agno agent framework. - [Control a browser with Notte's reasoning engine](/cookbook/notte): Control browsers with AI using Steel's infrastructure and Notte's reasoning engine. - [Build an AI browser agent with Magnitude](/cookbook/magnitude): Use Steel with Magnitude for AI-powered browser automation. - [Build a browser agent with Browser Use](/cookbook/browser-use): Integrate Steel with the browser-use framework for AI-driven web automation. - [Solve CAPTCHAs automatically in a Browser Use agent](/cookbook/browser-use-captcha-auto): Build an AI agent with browser-use and Steel that solves CAPTCHAs automatically. # Authentication URL: https://docs.steel.dev/cookbook/topics/authentication - [Persist authenticated sessions with Profiles](/cookbook/profiles): Maintain authenticated sessions across Steel browser instances using profiles. - [Reuse authenticated sessions across browsers](/cookbook/auth-context): Maintain authenticated sessions across Steel browser instances by capturing and reusing cookies and local storage. - [Automate logins with the Credentials API](/cookbook/credentials): Use the Steel Credentials API with Playwright to automate flows with stored credentials. # Browser automation URL: https://docs.steel.dev/cookbook/topics/browser-automation - [Run a Steel browser job with Trigger.dev](/cookbook/trigger-dev-browser-job): Queue a Trigger.dev task that creates a Steel session, drives Playwright over CDP, saves artifacts, and releases the browser in cleanup. - [Run a durable browser workflow with Temporal](/cookbook/temporal-browser-workflow): Build a Temporal TypeScript Workflow that schedules retryable Steel browser Activities to capture page summaries, screenshots, and Markdown artifacts. - [Automate a cloud browser with headless_chrome](/cookbook/headless-chrome): Use Steel with headless_chrome, the synchronous Rust equivalent of Puppeteer, to connect over CDP and scrape quotes with element handles. - [Automate a cloud browser with chromedp](/cookbook/chromedp): Use Steel with chromedp to connect over CDP, navigate to Hacker News, extract the top stories, and capture a screenshot. - [Automate a cloud browser with Rod](/cookbook/rod): Use Steel with Rod's fluent, chainable API to connect over CDP and scrape quotes.toscrape.com from a cloud browser. - [Automate a cloud browser with chromiumoxide](/cookbook/chromiumoxide): Use Steel with chromiumoxide to connect over CDP, drive the handler task, extract page content, and capture a screenshot. - [Automate browsing with natural-language instructions using Stagehand](/cookbook/stagehand): Use Steel with Stagehand for natural-language-driven AI browser automation. - [Automate a cloud browser with Playwright](/cookbook/playwright): Use Steel with Playwright in TypeScript for cloud browser automation. - [Automate a cloud browser with Puppeteer](/cookbook/puppeteer): Use Steel with Puppeteer in TypeScript for cloud browser automation. - [Automate a cloud browser with Selenium](/cookbook/selenium): Use Steel with Selenium in Python for cloud browser automation. ## Related integrations - [Steel + Playwright](/integrations/playwright): Drive a Steel browser with Playwright over CDP. - [Steel + Puppeteer](/integrations/puppeteer): Drive a Steel browser with Puppeteer over CDP. - [Steel + Selenium](/integrations/selenium): Drive a Steel browser with Selenium. # Browser Use URL: https://docs.steel.dev/cookbook/topics/browser-use - [Solve reCAPTCHA v2 manually with Browser Use](/cookbook/browser-use-captcha-manual): Manually solve reCAPTCHA v2 using Steel's CAPTCHA API with the browser-use framework. - [Build a browser agent with Browser Use](/cookbook/browser-use): Integrate Steel with the browser-use framework for AI-driven web automation. - [Solve CAPTCHAs automatically in a Browser Use agent](/cookbook/browser-use-captcha-auto): Build an AI agent with browser-use and Steel that solves CAPTCHAs automatically. ## Related integrations - [Steel + Browser Use](/integrations/browser-use): Set up Steel with the browser-use framework. # Captchas URL: https://docs.steel.dev/cookbook/topics/captchas - [Solve reCAPTCHA v2 manually with Browser Use](/cookbook/browser-use-captcha-manual): Manually solve reCAPTCHA v2 using Steel's CAPTCHA API with the browser-use framework. - [Solve CAPTCHAs automatically in a Browser Use agent](/cookbook/browser-use-captcha-auto): Build an AI agent with browser-use and Steel that solves CAPTCHAs automatically. ## Related guides - [Solving CAPTCHAs](/overview/stealth/captcha-solving): How Steel detects and solves CAPTCHA challenges. - [Proxies](/overview/stealth/proxies): Route traffic through proxies to reduce CAPTCHA challenges. # Computer use URL: https://docs.steel.dev/cookbook/topics/computer-use - [Drive a browser with Gemini Computer Use](/cookbook/gemini-computer-use): Connect Google's Gemini Computer Use to a Steel browser session for autonomous web interactions. - [Drive a mobile browser with Claude Computer Use](/cookbook/claude-computer-use-mobile): Claude Computer Use with Steel for autonomous task execution in mobile browser environments. - [Drive a browser with Claude Computer Use](/cookbook/claude-computer-use): Connect Claude to a Steel browser session for autonomous web interactions. - [Drive a browser with OpenAI Computer Use](/cookbook/openai-computer-use): Connect OpenAI's Computer Use Assistant to a Steel browser session for autonomous web interactions. ## Related integrations - [Steel + Claude Computer Use](/integrations/claude-computer-use): Point Claude's computer-use loop at a Steel session. - [Steel + OpenAI Computer Use](/integrations/openai-computer-use): Point OpenAI's Computer Use Assistant at a Steel session. - [Steel + Gemini Computer Use](/integrations/gemini-computer-use): Point Gemini Computer Use at a Steel session. # Convex URL: https://docs.steel.dev/cookbook/topics/convex - [Chat with any webpage on Convex](/cookbook/convex-chat-with-page): Convex app that streams an AI agent's answer about any URL. The agent runs server-side with one Steel-backed scrape tool and pages through long articles via a chunked cache. - [Watch Claude pricing for divergent A/B variants](/cookbook/convex-price-watch): Convex cron plus two parallel Steel proxy probes against claude.com/pricing. Stores per-tier per-region snapshots and surfaces tiers where the probes disagree. # MCP URL: https://docs.steel.dev/cookbook/topics/mcp - [Expose a Steel browser to any MCP client](/cookbook/mcp): Build a Model Context Protocol server in Go with the official SDK and chromedp that hands any MCP client a Steel cloud browser through explicit session-handle tools. # Mobile URL: https://docs.steel.dev/cookbook/topics/mobile - [Drive a mobile browser with Claude Computer Use](/cookbook/claude-computer-use-mobile): Claude Computer Use with Steel for autonomous task execution in mobile browser environments. ## Related integrations - [Steel + Claude Computer Use](/integrations/claude-computer-use): Drive Steel's mobile browser with Claude's computer-use model. # Next.js URL: https://docs.steel.dev/cookbook/topics/nextjs - [Stream a browser agent into a Next.js chat app](/cookbook/vercel-ai-sdk-nextjs): A Next.js App Router chat app where a Vercel AI SDK agent drives a Steel cloud browser with embedded Live View. # Playwright URL: https://docs.steel.dev/cookbook/topics/playwright - [Automate a cloud browser with Playwright](/cookbook/playwright): Use Steel with Playwright in TypeScript for cloud browser automation. - [Upload and run browser extensions](/cookbook/extensions): Use the Steel Extensions API with Playwright to upload and run browser extensions. - [Move files between your machine and a cloud browser](/cookbook/files): Use the Steel Files API with Playwright to automate file uploads and downloads in the cloud. ## Related integrations - [Steel + Playwright](/integrations/playwright): Set up Steel with Playwright and connect over CDP. # Restate URL: https://docs.steel.dev/cookbook/topics/restate - [Run a durable browser agent with Restate](/cookbook/restate-agent): Build a Restate Virtual Object in TypeScript that uses durable OpenAI planning steps and Steel scraping to answer browser research questions. # Search URL: https://docs.steel.dev/cookbook/topics/search - [Combine You.com search with Steel browser actions](/cookbook/you-com-search): Pair the You.com Search and Contents APIs with a Steel cloud browser in a search-then-act LangChain agent that prefers the cheap path and only opens a session when interaction is required. # Steel APIs URL: https://docs.steel.dev/cookbook/topics/steel-apis - [Scrape a page to Markdown, screenshot, and PDF](/cookbook/scrape): Use the Steel TypeScript SDK's direct API to scrape a page to clean Markdown for LLM context, plus screenshot and PDF, with no browser library. - [Watch Claude pricing for divergent A/B variants](/cookbook/convex-price-watch): Convex cron plus two parallel Steel proxy probes against claude.com/pricing. Stores per-tier per-region snapshots and surfaces tiers where the probes disagree. - [Persist authenticated sessions with Profiles](/cookbook/profiles): Maintain authenticated sessions across Steel browser instances using profiles. - [Reuse authenticated sessions across browsers](/cookbook/auth-context): Maintain authenticated sessions across Steel browser instances by capturing and reusing cookies and local storage. - [Automate logins with the Credentials API](/cookbook/credentials): Use the Steel Credentials API with Playwright to automate flows with stored credentials. - [Upload and run browser extensions](/cookbook/extensions): Use the Steel Extensions API with Playwright to upload and run browser extensions. - [Move files between your machine and a cloud browser](/cookbook/files): Use the Steel Files API with Playwright to automate file uploads and downloads in the cloud. # Subagents URL: https://docs.steel.dev/cookbook/topics/subagents - [Deep research with Claude Agent SDK subagents](/cookbook/deep-research): Lead orchestrator dispatches parallel researcher subagents, each driving its own Steel browser, and synthesizes findings into a cited Markdown report. ## Related integrations - [Steel + Claude Agent SDK](/integrations/claude-agent-sdk): Build the orchestrator and subagents on Anthropic's agent loop. # Temporal URL: https://docs.steel.dev/cookbook/topics/temporal - [Run a durable browser workflow with Temporal](/cookbook/temporal-browser-workflow): Build a Temporal TypeScript Workflow that schedules retryable Steel browser Activities to capture page summaries, screenshots, and Markdown artifacts. # Trigger.dev URL: https://docs.steel.dev/cookbook/topics/triggerdev - [Run a Steel browser job with Trigger.dev](/cookbook/trigger-dev-browser-job): Queue a Trigger.dev task that creates a Steel session, drives Playwright over CDP, saves artifacts, and releases the browser in cleanup. # Typed output URL: https://docs.steel.dev/cookbook/topics/typed-output - [Build a browser agent with Google ADK](/cookbook/google-adk): Use Steel with Google's Agent Development Kit (ADK) for Go to build a tool-using browser agent that drives a chromedp session over CDP and reads Hacker News. - [Build a typed browser agent with Pydantic AI](/cookbook/pydantic-ai): Use Steel with Pydantic AI to build typed, provider-agnostic browser agents with dependency injection. - [Build a typed browser agent with LangGraph](/cookbook/langgraph): Use Steel with LangGraph to build a typed browser agent with an explicit state-machine loop and a structured-output formatter node. - [Build a typed browser agent with Mastra](/cookbook/mastra): Use Steel with Mastra to build a typed browser agent with the Mastra Model Router and Studio playground. - [Build a typed browser agent with the OpenAI Agents SDK](/cookbook/openai-agents): Use Steel with the OpenAI Agents SDK for TypeScript to build typed, tool-using browser agents. - [Build a typed browser agent with the Vercel AI SDK](/cookbook/vercel-ai-sdk): Use Steel with the Vercel AI SDK v6 ToolLoopAgent for typed, tool-using browser agents. - [Stream a browser agent into a Next.js chat app](/cookbook/vercel-ai-sdk-nextjs): A Next.js App Router chat app where a Vercel AI SDK agent drives a Steel cloud browser with embedded Live View. ## Related integrations - [Steel + Pydantic AI](/integrations/pydantic-ai): Return typed, schema-validated agent results with Pydantic AI. - [Steel + LangGraph](/integrations/langgraph): Return typed agent results with an explicit LangGraph state machine. - [Steel + Mastra](/integrations/mastra): Return typed agent results with Mastra. # Agent Traces API URL: https://docs.steel.dev/overview/agent-traces/api Use the Agent Traces API when you want the same activity timeline shown in the dashboard, but as JSON for analysis, replay, or internal tooling. ### GET /v1/sessions/\:id/agent-traces Returns the trace timeline for a finished or in-progress session. ```bash curl https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces \ -H "steel-api-key: $STEEL_API_KEY" ``` ```javascript const response = await fetch( `https://api.steel.dev/v1/sessions/${sessionId}/agent-traces`, { headers: { "steel-api-key": process.env.STEEL_API_KEY } }, ); const trace = await response.json(); ``` ### Response ```json { "events": [ { "type": "click", "timestamp": "2026-05-22T18:03:21.345Z", "page": { "url": "https://example.com/login" }, "target": { "role": "button", "accessibleName": "Sign in", "selector": { "css": "button[data-testid=sign-in]" } }, "pointer": { "x": 520, "y": 410 } } ], "total": 1, "hasMore": false } ``` | Field | Type | Notes | | ----- | ---- | ----- | | `events` | array | Timeline activities in chronological order. | | `total` | number | Number of activities returned. | | `hasMore` | boolean | Whether more activity data is available. | Each activity includes a small common envelope: | Field | Type | Notes | | ----- | ---- | ----- | | `type` | string | Activity type, such as `click`, `input`, `navigate`, `scroll`, `drag`, or `error`. | | `timestamp` | ISO 8601 string | When the activity happened. | | `endTimestamp` | ISO 8601 string | Present when the activity spans a range of time. | | `page` | object | Page context, usually including `url`. | | `target` | object | Element context when available. | Activity-specific details appear when relevant. For example, click activities can include `pointer`, typing activities can include `value`, keyboard activities can include `keyboard`, navigation activities can include `navigation`, and error activities can include `error`. ### Target Details When Steel can identify the element involved in an activity, `target` can include readable labels and useful selectors: ```json { "role": "button", "accessibleName": "Sign in", "text": "Sign in", "attributes": { "data-testid": "sign-in", "type": "submit" }, "selector": { "css": "button[data-testid=sign-in]" } } ``` Use target details as hints for review or replay. Some activities, such as navigation or errors, may not include a target. ### Filtering by Time You can limit results to a time range: ```bash curl "https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces?startTime=2026-05-22T18:00:00.000Z&endTime=2026-05-22T18:10:00.000Z" \ -H "steel-api-key: $STEEL_API_KEY" ``` | Query param | Notes | | ----------- | ----- | | `startTime` | Include activities at or after this ISO timestamp. | | `endTime` | Include activities at or before this ISO timestamp. | ### Errors | Status | Meaning | | ------ | ------- | | 401 | Missing or invalid `steel-api-key`. | | 403 | The session belongs to a different organization. | | 404 | No session with that ID. | | 429 | Rate limit hit. Retry after the `Retry-After` header. | ### Need help with the Agent Traces API? Reach out on the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section. # Agent Traces: Observability for Browser Agents URL: https://docs.steel.dev/overview/agent-traces/overview Open any recorded session in the dashboard and you'll find an **Agent Traces** tab next to Console Logs and Network. It turns the run into a timeline of agent activity, so you can see what happened without scrubbing through the whole recording. ### What you get | Capability | What it does | | ---------- | ------------ | | **Timeline** | One row per meaningful activity, with a verb, target label, page URL, and timestamp. | | **Video sync** | Click a row to jump the recording to the moment that activity happened. | | **Details** | Expand a row to inspect the relevant page, element, pointer, keyboard, or error details when available. | | **Exports** | Copy the run as markdown, download JSON, or grab a ZIP with markdown plus screenshots. | ### How to use it **Review the run.** Start with the timeline to understand the path the agent took: where it navigated, what it clicked, what it typed, where it paused, and where errors happened. **Jump to the evidence.** Select any row to move the video to that point in the session. This makes it much faster to debug failures, unexpected navigation, or moments where the agent picked the wrong element. **Hand off context.** Export the trace as markdown when you want another agent or teammate to understand and reproduce the run. Use JSON when you want to analyze the activity data programmatically. ### Built from the browser session Agent Traces are based on what happened in the browser session, not on what the agent claimed it did. When page context is available, traces include readable target labels and element details to make the run easier to inspect or reproduce. ### Quick look at the API Fetch the trace timeline for a session as JSON: ```bash curl https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces \ -H "steel-api-key: $STEEL_API_KEY" ``` ```json { "events": [ { "type": "click", "timestamp": "2026-05-22T18:03:21.345Z", "page": { "url": "https://example.com/login" }, "target": { "role": "button", "accessibleName": "Sign in", "selector": { "css": "button[data-testid=sign-in]" } } } ], "total": 1, "hasMore": false } ``` See the [API reference](/overview/agent-traces/api) for the response shape and examples. ### Use cases **Debugging an agent run.** Find the error or unexpected action in the timeline, click it, and the video jumps to the right moment. Two clicks instead of ten minutes of scrubbing. **Reproducing a run as code.** Paste the markdown export into Claude Code, Codex, or Cursor with "write me a Steel script that reproduces this." The export is structured so an agent can follow the same path. **Evaluating agent versions.** Replay the same task against different models or prompts, then compare traces to see which version took fewer steps or handled the page more reliably. **Auditing what an agent actually did.** A timestamped, video-synced record of every interaction in one scrollable view. Useful for customer support investigations, safety reviews, and post-mortems. ### Where to go next Read [Timeline and exports](/overview/agent-traces/timeline) for the dashboard UI and export formats, or jump to the [API reference](/overview/agent-traces/api) for the REST endpoint. ### Need help with Agent Traces? Reach out on the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section. ### FAQ ### What are Agent Traces in Steel? Agent Traces turn a recorded browser session into a readable timeline of agent activity, with one row per meaningful action showing a verb, target label, page URL, and timestamp. You'll find the Agent Traces tab next to Console Logs and Network when you open any recorded session in the dashboard. ### Can I export an agent trace? Yes. You can copy the run as markdown, download JSON for programmatic analysis, or grab a ZIP containing markdown plus screenshots. The markdown export is structured so you can paste it into Claude Code, Codex, or Cursor and ask for a Steel script that reproduces the run. # Timeline and exports URL: https://docs.steel.dev/overview/agent-traces/timeline The Agent Traces tab lives in the session viewer console, next to Console Logs and Network. Open a session from the dashboard and switch tabs. ### Anatomy of a row Each row summarizes one meaningful browser activity. From left to right: | Element | What it shows | | ------- | ------------- | | **Icon + verb** | The type of activity, such as `click`, `input`, `navigate`, `scroll`, `drag`, or `error`. | | **Target label** | A readable name for the element when one is available, such as `Sign in` or `Email field`. | | **Page context** | The URL the activity happened on. Consecutive rows on the same page are grouped together. | | **Timestamp** | Wall clock plus an offset from session start for cross-referencing with the video. | Rows read like sentences: `click on Sign in`, `type into Email field`, `navigate to /home`. ### Activity grouping Agent Traces group noisy browser interactions into the units you would actually describe when reviewing a run. A burst of typing is shown as a single input activity, repeated navigation is easier to scan, and idle periods help separate thinking from acting in longer sessions. This makes the timeline useful for review without turning it into a raw event log. ### Video sync The timeline and the video are linked. Clicking a row seeks the recording to the moment that activity happened. Activity markers appear on the video progress bar, so you can see where the run was dense with actions and where it slowed down. As the video plays, the matching timeline row highlights. ### Details Click a row to expand it inline. Depending on the activity, details can include: - The page URL at the moment the activity happened. - Element context such as role, accessible name, visible text, and useful attributes. - Selectors when available. - Pointer, keyboard, navigation, or error details. - A thumbnail from the recording near that moment. For `navigate` rows, the **Open** button opens the URL in a new tab. ### Exports Three export formats are available from the Agent Traces tab on a finished session. | Export | What you get | Use when | | ------ | ------------ | -------- | | **Copy as markdown** | A single markdown document, built for pasting into another agent. | You want the next agent to read and reproduce the run. | | **Download JSON** | The activity data for the session. | You want to filter, diff, or analyze the run programmatically. | | **Download ZIP** | The markdown document plus screenshots, bundled in one archive. | You want a portable record for a bug report, support ticket, or audit. | #### Copy as markdown This is the export built for AI agents. The output reads like a recipe an automation agent can follow. The format includes: - A short preamble that explains the structure. - `##` headings for each page visit. - Numbered steps for each activity, with the time offset. - Relevant element labels, identifiers, and selectors when available. - Idle markers between longer pauses. - Sensitive values, such as password fields and credit-card inputs, replaced with ``. - Optional screenshots of page states. A trimmed example: ```markdown # Browser session Recording of a real browser session, structured for review and replay by an automation agent. ## https://example.com/login 1. `0:02.345` **Click** textbox "Email" - testId: `email` - CSS: `input[data-testid=email]` 2. `0:03.110` **Type** "user@example.com" into textbox "Email" - testId: `email` - CSS: `input[data-testid=email]` 3. `0:04.802` **Type** into textbox "Password" - name: `password` - CSS: `input[name=password]` *(idle 12s)* 4. `0:17.430` **Click** button "Sign in" - testId: `sign-in` - CSS: `button[data-testid=sign-in]` ## https://example.com/home ``` Paste it into Claude Code, Codex, OpenCode, or Cursor with `write me a Steel script that reproduces this run`. #### Download JSON The JSON export contains the session metadata and activity data. Use it when you want to filter, diff, or feed the run into your own tooling rather than another LLM. #### Download ZIP The ZIP bundles the markdown document with screenshots of page states. The screenshots are referenced from the markdown, so unzipping and opening the `.md` gives you a portable transcript. ### Redaction is automatic for known-sensitive fields Password fields and credit-card inputs are replaced with `` in both the markdown export and the ZIP. Other input values can appear in exports, so review before sharing if you ran the agent against real user data. ### Need help with Agent Traces? Reach out on the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section. # Browser Tools URL: https://docs.steel.dev/overview/browser-tools/overview Browser Tools are stateless, single-call endpoints that spin up a managed browser, perform one action against a URL, and return the result. They are the fastest way to pull content off a page when you do not need to drive a long-running session. | Endpoint | What it does | | ----------------- | --------------------------------------------------------------------- | | `POST /v1/scrape` | Loads a URL and returns HTML, cleaned HTML, Markdown, or Readability. | | `POST /v1/screenshot` | Loads a URL and returns a hosted PNG of the page. | | `POST /v1/pdf` | Loads a URL and returns a hosted PDF of the page. | Each call counts as 1 credit and is rate limited to 20 requests per minute per organization. Reach for [Sessions](/overview/sessions-api/overview) instead when you need cookies, multi-step navigation, or extension state. ### Scrape `POST /v1/scrape` extracts the contents of a single page. The response always includes `content`, `metadata`, and `links`; pass `format` to control which content variants come back. ```typescript import Steel from "steel-sdk"; const client = new Steel(); const result = await client.scrape({ url: "https://docs.steel.dev", format: ["markdown", "readability"], }); console.log(result.content.markdown); console.log(result.metadata.title); ``` ```python from steel import Steel client = Steel() result = client.scrape( url="https://docs.steel.dev", format=["markdown", "readability"], ) print(result.content.markdown) print(result.metadata.title) ``` The supported formats map to fields on `content`: | Format | Field | Use when | | -------------- | ---------------------- | --------------------------------------------------------- | | `html` | `content.html` | You want the raw DOM after JS execution. Default if `format` is omitted. | | `cleaned_html` | `content.cleaned_html` | You want stripped-down HTML without scripts, styles, ads. | | `markdown` | `content.markdown` | You're feeding the page into an LLM. | | `readability` | `content.readability` | You want Mozilla Readability's article extraction object. | `metadata` carries the usual SEO fields (`title`, `description`, `canonical`, Open Graph tags, JSON-LD, `statusCode`, etc.) and `links` is a flat array of every anchor on the page. ```json { "content": { "markdown": "# Steel Docs\n\n..." }, "metadata": { "title": "Steel Docs", "description": "...", "statusCode": 200, "ogImage": "https://docs.steel.dev/og.png" }, "links": [ { "url": "https://docs.steel.dev/cookbook", "text": "Cookbook" } ] } ``` #### Bundle a screenshot or PDF Set `screenshot: true` or `pdf: true` on a scrape call to capture both content and a hosted file in a single request. The screenshot and PDF come back as hosted URLs alongside the scraped content. ```typescript const result = await client.scrape({ url: "https://docs.steel.dev", format: ["markdown"], screenshot: true, pdf: true, }); console.log(result.screenshot?.url); console.log(result.pdf?.url); ``` ```python result = client.scrape( url="https://docs.steel.dev", format=["markdown"], screenshot=True, pdf=True, ) print(result.screenshot.url if result.screenshot else None) print(result.pdf.url if result.pdf else None) ``` ### Screenshot `POST /v1/screenshot` returns a hosted PNG. Use `fullPage: true` to capture the entire scrollable page instead of just the viewport. ```typescript const result = await client.screenshot({ url: "https://docs.steel.dev", fullPage: true, }); console.log(result.url); // https://files.steel.dev/v1/static/.png ``` ```python result = client.screenshot( url="https://docs.steel.dev", full_page=True, ) print(result.url) ``` The hosted URL is public and durable. Download it like any other PNG: ```typescript import fs from "node:fs"; const response = await fetch(result.url); const buffer = Buffer.from(await response.arrayBuffer()); fs.writeFileSync("page.png", buffer); ``` ### PDF `POST /v1/pdf` renders the page and returns a hosted PDF URL. Same shape as screenshot: one URL in, one URL out. ```typescript const result = await client.pdf({ url: "https://docs.steel.dev", }); console.log(result.url); // https://files.steel.dev/v1/static/.pdf ``` ```python result = client.pdf( url="https://docs.steel.dev", ) print(result.url) ``` ### Shared options All three endpoints accept the same handful of options for controlling how the page is loaded. | Option | Type | What it does | | ---------- | --------- | ---------------------------------------------------------------------------------- | | `useProxy` | `boolean` | Route the request through a Steel-managed residential proxy. Paid plans only. | | `delay` | `number` | Milliseconds to wait after navigation before capturing. Useful for hydrated sites. | A common pattern for client-rendered pages is to combine `delay` with a residential proxy: ```typescript const result = await client.scrape({ url: "https://example.com/pricing", format: ["markdown"], delay: 5000, useProxy: true, }); ``` ```python result = client.scrape( url="https://example.com/pricing", format=["markdown"], delay=5000, use_proxy=True, ) ``` ### Hobby plans cannot use Steel proxies on Browser Tools `useProxy: true` returns `402 Payment Required` on the hobby plan. Upgrade, or pass your own proxy by opening a [Session](/overview/sessions-api/overview) and scraping through it. ### Errors | Status | Meaning | | ------ | ---------------------------------------------------------------- | | 402 | `useProxy: true` requested on a plan that does not allow it. | | 408 | The browser timed out before completing the action. | | 429 | Concurrent session limit for your plan reached, or 20 RPM hit. | | 503 | No browser capacity available right now. Safe to retry. | ### When to use Sessions instead Browser Tools are stateless. Each call opens a fresh browser, performs the action, and tears down. Reach for a [Session](/overview/sessions-api/overview) when you need to: - Persist cookies or local storage across navigations - Submit forms, click through flows, or interact with the page - Pin a proxy to a specific country (`useProxy: { geolocation: { country } }`) - Reuse an authenticated profile or extension You can still scrape, screenshot, or generate a PDF from inside a session. The Browser Tools endpoints are just the shortcut when you don't need the rest. ### Need help with Browser Tools? Reach out to us on the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section. ### FAQ ### Should I use Browser Tools or Sessions? Use Browser Tools (`/v1/scrape`, `/v1/screenshot`, `/v1/pdf`) for stateless one-shot actions against a URL; each call spins up a fresh browser and tears it down. Reach for Sessions when you need to persist cookies, click through multi-step flows, pin a proxy to a country, or reuse an authenticated profile or extension. ### What formats can the scrape endpoint return? Pass `format` to get `html` (raw DOM after JS execution, the default), `cleaned_html`, `markdown` (best for feeding LLMs), or `readability` (Mozilla Readability's article object). Every response also includes `metadata` (SEO fields, status code) and a `links` array. # Overview URL: https://docs.steel.dev/overview/captchas-api/overview Steel's CAPTCHA system is designed to work seamlessly with browser automation workflows, automatically detecting and solving CAPTCHAs without interrupting your automation flow. Steel's CAPTCHAs API provides a robust solution for handling CAPTCHAs that appear during your automations. The system uses a bridge architecture that connects browser sessions with our CAPTCHA-solving capabilities, enabling real-time detection, solving, and state management. CAPTCHA solving is particularly useful for: * Scraping jobs that encounter CAPTCHA challenges * Browser workflows that need to submit forms or handle authentication flows * AI agents that need to navigate CAPTCHA-protected websites ### Session Configuration To enable autosolving, simply set `solveCaptcha: true` when creating a session. ```typescript import Steel from 'steel-sdk'; const client = new Steel(); const session = await client.sessions.create({ solveCaptcha: true }); ``` ```python from steel import Steel client = Steel() session = client.sessions.create( solve_captcha=True ) ``` To detect CAPTCHAs without automatically solving them, disable `autoCaptchaSolving` in the stealth config: ```typescript const session = await client.sessions.create({ solveCaptcha: true, stealthConfig: { autoCaptchaSolving: false } }); ``` ```python session = client.sessions.create( solve_captcha=True, stealth_config={ "autoCaptchaSolving": False } ) ``` ### How CAPTCHA Solving Works with the CAPTCHAs API Steel's CAPTCHAs API operates through a bridge architecture that connects your browser sessions with our external CAPTCHA-solving capabilities. It helps with four key parts: 1. **Detection**: The system automatically detects when CAPTCHAs appear on pages 2. **State Management**: CAPTCHA states are tracked per page with real-time updates 3. **Solving**: CAPTCHAs are then solved by us using various methods 4. **Completion**: The system reports back when CAPTCHAs are solved or failed ### Getting CAPTCHA Status You can check the current CAPTCHA status for any session to understand what CAPTCHAs are active and their current solving progress. ```typescript import Steel from 'steel-sdk'; const client = new Steel(); const response = await client.sessions.captchas.status('sessionId'); console.log(response); ``` ```python from steel import Steel client = Steel() response = client.sessions.captchas.status( "sessionId", ) print(response) ``` #### Response Format The status endpoint returns an array of current pages and their CAPTCHA states. An example output might look like: ```json [ { "pageId":"page_12345", "url":"https://example.com/login", "isSolvingCaptcha":true, "tasks":[ { "id":"task_67890", "type":"image_to_text", "status":"solving", "created":1640995200000, "url":"https://example.com/login", "pageId":"page_12345", "detectionTime":1640995200500, "totalDuration":5000, "solveTime":1640995205500 } ], "created":1640995200000, "lastUpdated":1640995205500 } ] ``` #### CAPTCHA Task Status Tasks can have the following statuses: * `undetected`: CAPTCHA has not been detected * `detected`: CAPTCHA has been detected but solving hasn't started * `validating`: CAPTCHA is currently being validated * `validation_failed`: CAPTCHA token failed validation after submission * `solving`: CAPTCHA is currently being solved * `solved`: CAPTCHA has been successfully solved * `failed_to_detect`: CAPTCHA detection failed * `failed_to_solve`: CAPTCHA solving failed ### Manual Solving If auto-solving is disabled, use the solve endpoint to trigger solving. You can solve all detected CAPTCHAs or target specific ones. The `taskId`, `url`, and `pageId` required for targeting specific CAPTCHAs can be retrieved from the CAPTCHA status response. When using `taskId`, use the value from the task's `id` field. ```typescript // Solve all detected CAPTCHAs await client.sessions.captchas.solve('sessionId'); // Solve specific task await client.sessions.captchas.solve('sessionId', { taskId: 'task_123' }); // Solve by URL await client.sessions.captchas.solve('sessionId', { url: 'https://example.com' }); // Solve by Page ID await client.sessions.captchas.solve('sessionId', { pageId: 'page_123' }); ``` ```python # Solve all detected CAPTCHAs client.sessions.captchas.solve("sessionId") # Solve specific task client.sessions.captchas.solve("sessionId", task_id="task_123") # Solve by URL client.sessions.captchas.solve("sessionId", url="https://example.com") # Solve by Page ID client.sessions.captchas.solve("sessionId", page_id="page_123") ``` ### Solving Image CAPTCHAs For image-based CAPTCHAs, you can provide XPath selectors to help the system locate and solve the CAPTCHA. The `url` parameter is optional and defaults to the current page. ```typescript import Steel from 'steel-sdk'; const client = new Steel(); const response = await client.sessions.captchas.solveImage('sessionId', { imageXPath: '//img[@id="captcha-image"]', inputXPath: '//input[@name="captcha"]', }); console.log(response.success); ``` ```python from steel import Steel client = Steel() response = client.sessions.captchas.solve_image( session_id=session.id, image_x_path='//img[@id="captcha-image"]', input_x_path='//input[@name="captcha"]', ) print(response.success) ``` #### Parameters * `imageXPath` (required): XPath selector for the CAPTCHA image element * `inputXPath` (required): XPath selector for the CAPTCHA input field * `url` (optional): URL where the CAPTCHA is located (defaults to current page) #### Response ```json { "success": true, "message": "Image captcha solve request sent" } ``` ### WebSocket Bridge The CAPTCHA bridge uses WebSocket connections to maintain real-time communication between browser sessions and CAPTCHA-solving extensions. This enables: * **Real-time state updates**: Immediate notification when CAPTCHAs are detected or solved * **Bidirectional communication**: Extensions can send updates and receive solve requests * **Persistent connections**: Maintains connection throughout the session lifecycle ### State Management The CAPTCHA bridge uses intelligent state management to handle complex scenarios: #### Page-Based Tracking States are tracked by `pageId` rather than URL to avoid duplicates and handle dynamic URLs effectively. #### Task Merging When multiple updates occur for the same CAPTCHA task, the system intelligently merges the information, preserving important details like: * Creation and detection timestamps * Solving duration calculations * Status progression #### Duration Calculation The system automatically calculates task durations based on: * `created` or `detectedTime`: When the CAPTCHA was first detected * `solveTime` or `failureTime`: When the CAPTCHA was solved or failed * Real-time updates during the solving process ### Integrating with Existing Automations Steel's CAPTCHA system is designed to work seamlessly with your existing automations using Playwright/Puppeteer: #### Monitoring CAPTCHA Progress ```typescript async function waitForCaptchaSolution(sessionId, timeout = 30000) { const startTime = Date.now(); while (Date.now() - startTime < timeout) { const status = await getCaptchaStatus(sessionId); const activeCaptchas = status.filter(state => state.isSolvingCaptcha); if (activeCaptchas.length === 0) { console.log('All CAPTCHAs solved!'); return true; } // Log progress activeCaptchas.forEach(captcha => { console.log(`CAPTCHA on ${captcha.url}: ${captcha.tasks.length} tasks`); }); await new Promise(resolve => setTimeout(resolve, 1000)); } throw new Error('CAPTCHA solving timeout'); } ``` #### Basic Integration Pattern ```typescript // Navigate to a page that might have CAPTCHAs await page.goto('https://example.com/protected-page'); // Check if CAPTCHAs are present const captchaStatus = await checkCaptchaStatus(sessionId); if (captchaStatus.some(state => state.isSolvingCaptcha)) { // Wait for CAPTCHA to be solved await waitForCaptchaSolution(sessionId); } // Continue with automation await page.click('#submit-button'); ``` #### Handling Different CAPTCHA Types The CAPTCHA bridge automatically handles most common CAPTCHA types. For image CAPTCHAs, you can use the image solving endpoint with specific XPath selectors. The captcha types for each task are mapped to the CAPTCHA types we support like so: * `recaptchaV2`: Google's reCAPTCHA v2 with "I'm not a robot" checkbox and image challenges * `recaptchaV3`: Google's reCAPTCHA v3 with invisible background scoring and risk analysis * `turnstile`: Cloudflare Turnstile with minimal user interaction verification * `image_to_text:` Traditional text-based CAPTCHA requiring OCR of distorted characters #### Best Practices 1. **Monitor State Changes**: Regularly check CAPTCHA status during automation 2. **Handle Timeouts**: Set reasonable timeouts for automatic CAPTCHA solving operations 3. **Use Specific Selectors**: Provide accurate XPath selectors for image CAPTCHAs 4. **Error Handling**: Implement proper error handling for failed CAPTCHA attempts 5. **Logging**: Log CAPTCHA events for debugging and monitoring The CAPTCHA system is designed to be as transparent as possible to your automation workflows, handling the complexity of CAPTCHA detection and solving while providing you with the control and visibility you need. ### Need help building with the Captchas API? Reach out to us on the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section. ### FAQ ### Does Steel solve CAPTCHAs automatically? Yes — set `solveCaptcha: true` when creating a session and Steel automatically detects and solves CAPTCHAs without interrupting your automation flow. ### Can Steel detect CAPTCHAs without solving them? Yes — set `autoCaptchaSolving: false` in the session's `stealthConfig` to detect CAPTCHAs without auto-solving, then trigger solving manually via the solve endpoint (all detected CAPTCHAs, or a specific `taskId`, `url`, or `pageId`). ### What CAPTCHA types does Steel's CAPTCHAs API handle? Tasks are mapped to four supported types: `recaptchaV2` (checkbox and image challenges), `recaptchaV3` (invisible scoring), `turnstile` (Cloudflare), and `image_to_text` (traditional distorted-character CAPTCHAs). ### How do I check if a CAPTCHA is being solved in my Steel session? Call the status endpoint (`client.sessions.captchas.status('sessionId')`) — it returns each page's `isSolvingCaptcha` flag plus per-task statuses like `detected`, `solving`, `solved`, and `failed_to_solve`. ### How does Steel solve image-based CAPTCHAs? Via the `solveImage` endpoint — you pass `imageXPath` (the CAPTCHA image element) and `inputXPath` (the answer field), both required, plus an optional `url` that defaults to the current page. # Credentials API URL: https://docs.steel.dev/overview/credentials-api/overview # Overview Securely store and inject login credentials into browser sessions without exposing them to agents or the page. Steel's Credential system is currently in beta and is subject to improvements, updates, and changes. It will be free to use and store credentials during this period. If you have feedback, join our Discord or open an issue on GitHub. Steel's Credentials system is designed to allow developers to securely store credentials, inject them into sessions, and automatically sign-into websites. All without leaking sensitive data back to the agents, programs, or humans viewing a live session. Some of the most important use-cases for AI agents are hidden behind an auth wall. Some of the data most important to both our work and personal lives live inside sign-in-protected applications. If we want browser agents to help us automate the most tedious aspects of our lives, they need access to those same applications. The problem is sending your personal credentials (username/passwords, etc) to a browser-agent, powered by an opaque LLM API that may or may not be training on your data, represents a non-trivial security risk. Further, the process of logging in can be error prone and keeping/storing credentials on behalf of users, as an application developer, can represent a ton of responsibility and overhead. That is the motivation behind Steel's Credentials system. Credentials are stored globally against your organization, so once created, you can reuse them in any session going forward – no need to constantly re-enter or re-provision them. Steel's Credentials system is built around three core goals: - Secure storage of credentials using enterprise-grade encryption. - Controlled injection into browser sessions without exposing sensitive fields. - Isolation mechanisms to prevent agents from extracting secrets post-injection. ### Table of Contents - [Getting Started](#getting-started) - [Injecting Credentials into a Session](#injecting-credentials-into-a-session) - [TOTP Support](#totp-support) - [How credentials are injected](#how-credentials-are-injected) - [Envelope encryption](#envelope-encryption) - [Using with Agent Frameworks](#using-with-agent-frameworks) ## Getting Started Before credentials can be used in a browser session, they must first be uploaded and stored securely. All credentials are stored globally against your organization. You only need to create them once. To upload credentials: ```typescript await client.credentials.create({ origin: "https://app.example.com", value: { username: "test@example.com", password: "password123" } }); ``` ```python client.credentials.create( origin="https://app.example.com", value={ "username": "test@example.com", "password": "password123" } ) ``` These credentials are encrypted and stored securely within Steel’s credential management service. The `namespace` field helps separate use cases for the same origin and must match the namespace used when creating the session. For more information on how namespaces work [visit the namespace section](#namespaces). You can optionally include a `totpSecret` field if your login flow uses one-time passwords (see [TOTP Support](#totp-support)). ## Injecting Credentials into a Session When starting a session via `POST /sessions`, you can request credential injection using the optional `credentials` field: ```typescript const session = await client.sessions.create({ namespace: "default", credentials: {} }); ``` ```python client.sessions.create( namespace="default", credentials={} ) ``` If the `credentials` object is omitted, no credentials will be injected. If included as an empty object (`credentials: {}`), the default options apply: ```json { "autoSubmit": true, "blurFields": true, "exactOrigin": true } ``` - `autoSubmit`: If `true`, the form will automatically submit once filled. - `blurFields`: If `true`, each filled field is blurred immediately after input, preventing access. - `exactOrigin`: If `true`, credentials will only inject into pages that match the exact origin. You can override any of these to suit your use-case. Remember to match the `namespace` with the one used in your credential creation, if omitted, it defaults to `"default"`. Once the session is active and on the login page, credentials are typically injected within **2 seconds**. If `autoSubmit` is disabled, the agent or user must manually click the login button. ## TOTP Support Steel supports auto-filling TOTP (Time-based One-Time Passwords). To use this feature, include a `totpSecret` in the `value` object when uploading credentials: ```json { "username": "test@example.com", "password": "password123", "totpSecret": "JBSWY3DPEHPK3PXP" } ``` The secret is securely stored and never exposed to the page. When a one-time password field is detected, Steel generates a valid code on-demand and injects it directly. ## How Credentials are Injected The system is responsible for securely retrieving and injecting them into service webpages. This happens through a general background communication layer that connects to a secure credential service. ### Overview: how the service fills credentials in a page 1. The credential service loads a lightweight script into each active page and frame. 2. On startup, it watches for forms or login components using mutation observers and shadow DOM traversal. 3. When a valid credential target is detected, it is validated and ranked. 4. The top-ranked candidate is selected as the active target. 5. Observers are attached to the relevant input fields and forms. 6. The credential service requests credentials matching the current org, namespace, and target origin. 7. Once decrypted, credentials are injected directly into the selected form fields. 8. Inputs are updated programmatically, preserving synthetic events and page behavior. 1. We detect and only inject credentials into a username, password, and one-time password field. The username field is generic and we try our best to map any identifier to this property (email, identifier, username, etc.). 2. inputs are blurred once a value is inserted (configurable) to prevent vision agents from reading PII 9. The form is submitted either natively or via simulated interaction, depending on the form structure if autoSubmit is configured. 10. Updates to the DOM are continuously monitored to adapt to dynamic changes in the page. ## Envelope encryption Envelope encryption is a secure and scalable pattern where data is encrypted using a randomly generated data key (usually with a symmetric algorithm like AES), and that data key is then encrypted with a master key managed by a key management store (KMS). Each credential is protected with its own short‑lived AES‑256‑GCM key. The key is then encrypted with a private KMS key specific to an organization. The encrypted data and the encrypted key travel together. At decryption time, the inverse happens where we then get the encrypted AES key, decrypt it using the specific key pair for the KMS and then use this decrypted AES key to decrypt the credential. The clear-text credentials are placed directly into the in-memory session and sent to the target service over our private WireGuard backbone ensuring end-to-end encryption and safe keeping of your credentials. #### Additional authenticated data (AAD) We bind the cipher-text to its context by including the org ID and credential origin as AAD. A mismatch during decrypt causes the operation to fail which blocks replay attacks across orgs. ## Namespaces Namespaces allow you to differentiate between multiple credentials for the same origin. This is useful when you need to store and use separate login details for different users or use cases. By default, all credentials and sessions are created under the `default` namespace. If you don’t specify a namespace, this is what will be used. #### Why Use Namespaces? If you have multiple credentials for the same website, namespaces help you control which one is used in a given session. For example, say you have two users who log in to the same domain: ```json // Credential A { "namespace": "example:fred", "origin": "https://app.example.com", "value": { "username": "fred@example.com", "password": "hunter2" } } // Credential B { "namespace": "example:jane", "origin": "https://app.example.com", "value": { "username": "jane@example.com", "password": "letmein" } } ``` To use **Fred’s** credentials in a session: ```json POST /sessions { "namespace": "example:fred", "credentials": {} } ``` This ensures only the credentials created under `example:fred` will be injected. #### Best Practices - Use simple, descriptive namespaces like `example:fred` or `test:jane`. - Stick to a consistent pattern (e.g., `org:user`) for better organization. - Always match the `namespace` in your session with the one used to create the credentials. Namespace matching is exact. There is no inheritance or wildcard matching—only credentials in the exact namespace provided will be used. ## Using with Agent Frameworks Steel is designed to integrate seamlessly with browser automation tools and agent frameworks such as `browser-use` and similar libraries. While we don’t yet expose framework-specific SDKs or utilities, the process is straightforward and works out of the box with minimal setup. #### How it Works Once credentials are linked to your session, injection and login will occur automatically as part of the page lifecycle. To make use of this in your agent or script, follow this basic pattern: 1. **Navigate** to the login page of the target website. 2. **Wait** at least 2 seconds to allow Steel to detect and fill the form. 3. **Continue** once logged in. If `autoSubmit` is enabled (which it is by default), the login form will be submitted automatically once the fields are populated and validated. If `autoSubmit` is disabled, you must explicitly trigger the login action (e.g., click the login button) after credentials are filled. #### Example Flow ```typescript await page.goto("https://app.example.com/login"); // Optional: ensure login form is present await page.waitForSelector("form"); // Wait for Steel to inject and (optionally) submit the form await page.waitForTimeout(2000); // Recommended: confirm login succeeded await page.waitForSelector(".dashboard"); // or some element/text that confirms login ``` #### Notes - Credential injection is bound to the session's namespace and the origin provided when the credential was created. - Injection will only occur on exact origins if `exactOrigin: true` (default). - The page must be fully loaded and interactive for injection to proceed reliably. We plan to release official helpers and utilities for common frameworks like `browser-use`, `Playwright`, and `Puppeteer` soon. For now, you can build on this guide to integrate Steel into your existing automation workflows. ### Need help building with the Credentials API? Reach out to us on the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section. ### FAQ ### How does Steel keep stored credentials secure? With envelope encryption — each credential is protected by its own short-lived AES-256-GCM key, which is in turn encrypted with an organization-specific KMS key. The ciphertext is also bound to your org ID and credential origin as additional authenticated data (AAD), which blocks replay attacks across orgs. ### Can AI agents see the passwords Steel injects? No — credentials are injected into login forms without being exposed to agents, programs, or humans viewing a live session, and each filled field is blurred immediately after input (`blurFields: true` by default) to prevent vision agents from reading PII. ### Does Steel's Credentials API support 2FA / TOTP logins? Yes — include a `totpSecret` in the credential's `value` object and Steel generates a valid time-based one-time password on demand when a TOTP field is detected. The secret is securely stored and never exposed to the page. # Overview URL: https://docs.steel.dev/overview/extensions-api/overview Steel’s Extensions system is currently in beta and is subject to improvements, updates, and changes. If you have feedback, join our Discord or open an issue on GitHub. Steel's extensions are designed to enhance the functionality of Steel sessions by providing additional features and capabilities. These extensions can be used to automate tasks, enhance security, and improve the overall agent experience. They can be installed through the API for your organization and attached to any session. Extensions have long been a part of the browser ecosystem, since the release of Internet Explorer version 4 in 1997, users have been able to create their own extensions and make their browser their own. With the advent of agentic browsing and browser agents, extensions have gained a whole new light. Allowing thousands of agents to extend their own browser sessions with custom functionality. ### Getting Started Before extensions can be used in a browser session, they must first be uploaded either with a .zip/.crx file or downloaded from the Chrome Web Store. All extensions are stored globally against your organization. You only need to upload them once. The supported formats include .zip and .crx ### Upload Extension From File The extensions uploaded have a couple of requirements. They need a preliminary manifest.json file to define the extension's metadata and functionality. This file should include details such as the extension's name, version, and any permissions required. ```typescript await client.extensions.upload({ file: fs.readFileSync('extensions/recorder/recorder.zip') }); ``` ```python with open("extensions/recorder/recorder.zip", "rb") as file: client.extensions.upload( file=file ) ``` ### Upload Extension from Chrome Web Store Go to the Chrome Web Store and click on the extension you want to upload. Copy the URL and include it in the request below ```typescript await client.extensions.upload({ url: "https://chromewebstore.google.com/detail/.../..." }); ``` ```python client.extensions.upload( url="https://chromewebstore.google.com/detail/.../..." ) ``` Once they are installed for your organization, you can inject them into your sessions. ### Injecting Extensions into a Session You can inject specific extensions into your sessions based on the `extensionId` field or you can pass `all_ext` to inject all extensions from your organization. ```typescript const session = await client.sessions.create({ extensionIds: ['all_ext'] // extensionIds=['extensionId_1', 'extensionId_2'] }); ``` ```python client.sessions.create( extension_ids=['all_ext'] # extension_ids=['extensionId_1', 'extensionId_2'] ) ``` And now your sessions have extensions! These extensions will be injected into the Steel browser session that then runs with that session. Extensions are loaded and initialized when the session starts. They can communicate with the session using the Chrome DevTools Protocol (CDP) and interact with the browser environment. ### Updating Extensions From File After using your extensions, you can update them by uploading a new version of the extension. You will need to specify the `extensionId` of the extension you want to update. ```typescript await client.extensions.update("{extensionId}",{ file: fs.readFileSync("extensions/recorder2/recorder2.zip") }); ``` ```python with open("extensions/recorder2/recorder2.zip", "rb") as file: client.extensions.update("{extensionId}", file=file ) ``` ### Updating Extensions From Chrome Web Store You will need to specify the `extensionId` of the extension you want to update ```typescript await client.extensions.update("{extensionId}",{ url: "https://chromewebstore.google.com/detail/.../..." }); ``` ```python client.extensions.update("{extensionId}", url="https://chromewebstore.google.com/detail/.../..." ) ``` ### Seeing your Extensions To see your organization's installed extensions, you can use the `GET /v1/extensions` endpoint. ```typescript const extensions = await client.extensions.list(); ``` ```python extensions = client.extensions.list() ``` ### Deleting an Extension To delete one of your organization's installed extensions, you can use the `DELETE /v1/extensions/{extensionId}` endpoint. ```typescript await client.extensions.delete("{extensionId}") ``` ```python client.extensions.delete("{extensionId}") ``` ### Deleting all Extensions To delete all of your organization's installed extensions, you can use the `DELETE /v1/extensions/` endpoint. ```typescript await client.extensions.deleteAll() ``` ```python client.extensions.deleteAll() ``` ### Need help building with the Extensions API? Reach out to us on the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section. ### FAQ ### Can I use Chrome extensions in Steel browser sessions? Yes. Upload an extension as a `.zip` or `.crx` file, or directly from a Chrome Web Store URL, then attach it to any session. Note the Extensions system is currently in beta. ### Do I have to upload an extension for every session? No. Extensions are stored globally against your organization, so you only upload them once and can then inject them into any session. ### How do I add extensions to a session? Pass specific extension IDs via the `extensionIds` field when creating the session, or pass `all_ext` to inject every extension installed for your organization. Extensions are loaded and initialized when the session starts. ### How do I update or remove an extension? Update by calling `client.extensions.update` with the `extensionId` and a new file or Chrome Web Store URL. Delete a single extension with `DELETE /v1/extensions/{extensionId}` or remove all of them with `DELETE /v1/extensions/`. # Overview URL: https://docs.steel.dev/overview/files-api/overview Steel provides two complementary file management systems: Session Files for working with files within active browser sessions, and Global Files for persistent file storage across your organization. ### Overview Steel's file management system makes it easy to work with files in your automated workflows: * **Session-Based File Operations**: Upload files to active sessions for immediate use in browser automations, download files acquired during browsing * **Persistent File Storage**: Maintain a global file repository for reuse across multiple sessions and workflows * **Workspace Management**: Organize and access files generated across different automation runs * **Data Pipeline Integration**: Upload datasets once and reference them across multiple automation sessions * **File Archival**: Automatically preserve files from completed sessions for later access ### How It Works #### Session Files System Files uploaded to active sessions become available within that session's isolated VM environment. These files can be used immediately with web applications and browser automation tools. When files are downloaded from the internet during a session, they become accessible through the same API. Session files persist beyond session lifecycle - files are automatically backed up when sessions end. #### Global Files System The Global Files API provides persistent, organization-wide file storage independent of browser sessions. Files uploaded to global storage can be referenced and mounted in any session. All session files are automatically promoted to global storage when sessions are released, creating a comprehensive file workspace. ### Session Files API This section outlines how to interact with the filesystem inside of the VM that your session is running from. All of these files are accessible from the browser. #### Upload Files to Session File System ```typescript // Upload file to session environment const file = fs.createReadStream("./steel.png"); const session = await client.sessions.create(); const uploadedFile = await client.sessions.files.upload(session.id, { file: file, // or path in global files api or absolute url }); ``` ```python import requests session_id = "YOUR_SESSION_ID" api_key = "YOUR_API_KEY_HERE" file_path = "./steel.png" with open(file_path, "rb") as f: response = requests.post( f"https://api.steel.dev/v1/sessions/{session_id}/files", headers={"steel-api-key": api_key}, files={"file": f} ) print(response.json()) ``` #### List Files in a Session File System ```typescript const files = await client.sessions.files.list(sessionId); files.data.forEach((file) => { console.log(`${file.path} | Size: ${file.size} | Last Modified: ${file.lastModified}`); }); ``` ```python import requests session_id = "YOUR_SESSION_ID" api_key = "YOUR_API_KEY_HERE" response = requests.get( f"https://api.steel.dev/v1/sessions/{session_id}/files", headers={"steel-api-key": api_key} ) for file in response.json()["data"]: print(f"{file['path']} | Size: {file['size']} | Last Modified: {file['lastModified']}") ``` #### Download Files from Session File System For raw HTTP requests, the `{path}` parameter is relative. Session file responses currently come back in a `/files/...` form, so strip that prefix before interpolating the value into the URL. ```typescript // Download a specific file from a session const response = await client.sessions.files.download(sessionId, "path/to/file"); const fileBlob = await response.blob(); // Download all files as zip archive const archiveResponse = await client.sessions.files.downloadArchive(sessionId); ``` ```python import requests session_id = "YOUR_SESSION_ID" api_key = "YOUR_API_KEY_HERE" # Download a specific file file_resp = requests.get( f"https://api.steel.dev/v1/sessions/{session_id}/files/path/to/file", headers={"steel-api-key": api_key} ) with open("downloaded_file", "wb") as f: f.write(file_resp.content) # Download all files as zip archive archive_resp = requests.get( f"https://api.steel.dev/v1/sessions/{session_id}/files.zip", headers={"steel-api-key": api_key} ) with open("session_files.zip", "wb") as f: f.write(archive_resp.content) ``` #### Delete Files from Sessions File System The raw HTTP delete endpoint also expects the relative path segment rather than the `/files/...` form returned by session file responses. ```typescript // Delete a specific file from a session const response = await client.sessions.files.delete(sessionId, "path/to/file"); // Delete all files in a session const archiveResponse = await client.sessions.files.deleteAll(session.id); ``` ```python import requests session_id = "YOUR_SESSION_ID" api_key = "YOUR_API_KEY_HERE" # Delete a specific file del_resp = requests.delete( f"https://api.steel.dev/v1/sessions/{session_id}/files/path/to/file", headers={"steel-api-key": api_key} ) print(del_resp.status_code) # Delete all files in a session del_all_resp = requests.delete( f"https://api.steel.dev/v1/sessions/{session_id}/files", headers={"steel-api-key": api_key} ) print(del_all_resp.status_code) ``` ### Global Files API #### Upload File to Global Storage ```typescript const file = fs.createReadStream("./dataset.csv"); const globalFile = await client.files.upload({ file, // path: "dataset.csv" // optional }); console.log(globalFile.path); // dataset.csv // Using the file from Global Files API in a session const session = await client.sessions.create(); const uploadedFile = await client.sessions.files.upload(session.id, { file: globalFile.path }); ``` ```python import requests api_key = "YOUR_API_KEY_HERE" file_path = "./dataset.csv" with open(file_path, "rb") as f: response = requests.post( "https://api.steel.dev/v1/files", headers={"steel-api-key": api_key}, files={"file": f} ) print(response.json()) ``` #### List All Files ```typescript const files = await client.files.list(); files.data.forEach((file) => { console.log(`${file.path} | Size: ${file.size} | Last Modified: ${file.lastModified}`); }); ``` ```python import requests api_key = "YOUR_API_KEY_HERE" response = requests.get( "https://api.steel.dev/v1/files", headers={"steel-api-key": api_key} ) for file in response.json()["data"]: print(f"{file['path']} | Size: {file['size']} | Last Modified: {file['lastModified']}") ``` #### Download Global File For raw HTTP requests, pass a relative `{path}` value here as well. ```typescript const response = await client.files.download(file.path); // dataset.csv const fileBlob = await response.blob(); ``` ```python import requests api_key = "YOUR_API_KEY_HERE" file_path = "dataset.csv" response = requests.get( f"https://api.steel.dev/v1/files/{file_path}", headers={"steel-api-key": api_key} ) with open(file_path, "wb") as f: f.write(response.content) ``` #### Delete Global File The raw HTTP delete endpoint expects the same relative `{path}` format used by the download endpoint. ```typescript await client.files.delete(file.path); ``` ```python import requests api_key = "YOUR_API_KEY_HERE" file_path = "dataset.csv" response = requests.delete( f"https://api.steel.dev/v1/files/{file_path}", headers={"steel-api-key": api_key} ) print(response.status_code) ``` ### Usage in Context #### Set File Input Values Reference uploaded files in file input elements using CDP (Chrome DevTools Protocol). ```typescript // Create CDP session for advanced controls const cdpSession = await currentContext.newCDPSession(page); const document = await cdpSession.send("DOM.getDocument"); // Find the input element const inputNode = await cdpSession.send("DOM.querySelector", { nodeId: document.root.nodeId, selector: "#file-input" }); // Set the uploaded file as input await cdpSession.send("DOM.setFileInputFiles", { files: [uploadedSessionFile.path], nodeId: inputNode.nodeId, }); ``` #### Standard Playwright/Puppeteer Upload ```typescript // For simple/smaller file uploads, // using standard automation library methods will look at local files await page.setInputFiles("#file-input", [uploadedSessionFile.path]); ``` #### Browser-Use Example Browser-use needs some setup before it can be used. This includes setting up the browser profile with the correct downloads path and adding in a step hook to extract downloaded files to your local machine if necessary. ```python # Before agent main loop... # Hook to extract downloaded files to local machine if necessary async def step_hook_start(agent): if os.environ.get("BROWSER_PROVIDER") == "steel": await agent._check_and_update_downloads() if agent.available_file_paths and len(agent.available_file_paths) > 0: has_new_files = False for file_path in agent.available_file_paths: if file_path not in downloaded_files: downloaded_files.append(file_path) has_new_files = True if has_new_files: try: extracted_files = await browser_service.extract_downloaded_files(DOWNLOAD_PATH) logger.info(f"Extracted files: {extracted_files}") except Exception as e: logger.error(f"Failed to extract downloaded files: {e}") async def main(): try: browser_session = Browser(cdp_url=cdp_url, downloads_path="/files") await browser_session.connect() await browser_session.cdp_client.send.Target.createBrowserContext() browser_context_ids_return = await browser_session.cdp_client.send.Target.getBrowserContexts() browser_context_ids = browser_context_ids_return['browserContextIds'] browser_context_id = browser_context_ids[0] await browser_session.cdp_client.send.Browser.setDownloadBehavior(params={"behavior": "allow", "downloadPath": "/files", "eventsEnabled": True, "browserContextId": browser_context_id}) agent = Agent(task=TASK, llm=model, browser_session=browser_session) agent.browser_session.browser_profile.downloads_path = LOCAL_DOWNLOAD_PATH agent_results = await agent.run( on_step_start=step_hook_start, max_steps=5 ) except Exception as e: print(f"Error: {e}") finally: # Clean up resources if session: client.sessions.release(session.id) print("Session released") print("Done!") # Rest of code... ``` #### Complete Example End-to-end workflow demonstrating global file management and session file operations. ```typescript import dotenv from "dotenv"; import fs from "fs"; import { chromium } from "playwright"; import Steel from "steel-sdk"; dotenv.config(); const client = new Steel({ steelAPIKey: process.env.STEEL_API_KEY, }); async function main() { let session; let browser; try { // Upload dataset to global storage for reuse const datasetFile = new File( [fs.readFileSync("./data/stock-data.csv")], "stock-data.csv", { type: "text/csv" } ); const globalFile = await client.files.upload({ file: datasetFile }); console.log(`Dataset uploaded to global storage: ${globalFile.path}`); // Create session and mount global file session = await client.sessions.create(); console.log(`Session created: ${session.sessionViewerUrl}`); const sessionFile = await client.sessions.files.upload(session.id, { file: globalFile.path }); // Connect browser and use the file browser = await chromium.connectOverCDP( `wss://connect.steel.dev?apiKey=${process.env.STEEL_API_KEY}&sessionId=${session.id}` ); const currentContext = browser.contexts()[0]; const page = currentContext.pages()[0]; // Navigate to data visualization tool await page.goto('https://www.csvplot.com/'); // Upload file to web application using CDP const cdpSession = await currentContext.newCDPSession(page); const document = await cdpSession.send("DOM.getDocument"); const inputNode = await cdpSession.send("DOM.querySelector", { nodeId: document.root.nodeId, selector: "#load-file", }); await cdpSession.send("DOM.setFileInputFiles", { files: [sessionFile.path], nodeId: inputNode.nodeId, }); // Wait for visualization and capture await page.waitForSelector("svg.main-svg"); // Download all session files (original upload + any generated files) const archiveResponse = await client.sessions.files.downloadArchive(session.id); const zipBlob = await archiveResponse.blob(); // Files are automatically available in global storage after session ends } catch (error) { console.error("Error:", error); } finally { if (browser) await browser.close(); if (session) await client.sessions.release(session.id); // List all available files in global storage const allFiles = await client.files.list(); console.log(`Total files in storage: ${allFiles.data.length}`); } } main(); ``` ### Need help building with the Files API? Reach out to us on the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section. ### FAQ ### How do I upload a file into a website's file input from a Steel session? Upload the file to the session first, then either use CDP's `DOM.setFileInputFiles` with the session file path, or for simpler cases use standard automation methods like Playwright's `page.setInputFiles` with the session file path. ### Can I download all files from a session at once? Yes. Use `client.sessions.files.downloadArchive(sessionId)` in the SDK, or hit the `files.zip` endpoint via raw HTTP, to download every file in the session as a single zip archive. # Overview URL: https://docs.steel.dev/overview/profiles-api/overview ### Overview Steel's profiles API allows you to create, update, and persist profiles across sessions. Profiles are used to store information about the browser session like auth, cookies, extensions, credentials, and browser settings. Then you can keep reusing profiles across sessions for each different use case. Think a LinkedIn profile, a GitHub profile, or a Facebook profile. This allows your agents to look more human, persist everything across sessions and frees you to focus on the most important part of your workflow. Profiles preserve browser identity. [Dedicated IPs](/overview/sessions-api/dedicated-ips) preserve network identity. For account-based agents, the strongest setup is usually one profile plus one dedicated IP per account, so sites see the same cookies, storage, and a familiar IP instead of a fresh browser from a new network every run. ### Limits - There is a 300 MB limit on the size of a profile, if the upload fails after a session, the profile will be set to a `FAILED` state and cannot be used - If a profile is not used after 30 days, it will be automatically deleted ### How Profiles Work Profiles work by storing a snapshot of the browser's User Data Directory. This includes all the data that is stored in the browser, such as cookies, extensions, credentials, and browser settings. 1. Session gets created with a `persistProfile` flag 2. Initial profile gets created with some information on the session and gets stored in an `UPLOADING` state 3. After the session is released, the userDataDir is persisted and the additional information on the profile is updated and the profile is set to the `READY` state 4. Whenever a session is created with the `profileId`, the profile is loaded from the storage and the session is started with the same userDataDir and context #### Persist a profile when starting a session ```typescript // Start a session and persist the profile const firstSession = await client.sessions.create({ persistProfile: true }) ``` ```python # Start a session and persist the profile first_session = client.sessions.create(persist_profile=True) ``` #### Start a second session with your new profile ```typescript // Start a session with the persisted profile const secondSession = await client.sessions.create({ profileId: firstSession.profileId }) ``` ```python # Start a session with the persisted profile second_session = client.sessions.create(profile_id=first_session.profile_id) ``` This will return a profileId from the session which will allow you to pass it into new sessions in the future. ### Persisting browser information automatically Persisting additional information about the browser session like auth, cookies, extensions, credentials, and browser settings is not on by default, to keep building up context with each session, pass persistProfile=True along with your profileId. #### Update your profile after a new session ```typescript // Update the profile with new information, this will update the profile with whatever happens in the session const thirdSession = await client.sessions.create({ profileId: firstSession.profileId, persistProfile: true }) ``` ```python # Update the profile with new information, this will update the profile with whatever happens in the session third_session = client.sessions.create(profile_id=first_session.profile_id, persist_profile=True) ``` ### Persisting browser information manually You can also manually create and update a profile via the Profiles API. This allows you to update the proxy, user-agent, or replace the entire userDataDir for your profile. #### Create your profile ```typescript // Create a new profile with new information await client.profiles.create({ userDataDir: fs.readFileSync('path/to/userDataDir.zip'), userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3'}) ``` ```python # Create a new profile with new information with open("path/to/userDataDir.zip", "rb") as file: client.profiles.create(user_data_dir=file, user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3') ``` #### Update your profile with some information ```typescript // Update the profile with new information, this will be used next session await client.profiles.update(firstSession.profileId, { userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3'}) ``` ```python # Update the profile with new information, this will be used next session client.profiles.update(first_session.profile_id, user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3') ``` ### FAQ ### What does a Steel profile actually store? A profile stores a snapshot of the browser's User Data Directory, which includes everything stored in the browser: auth, cookies, extensions, credentials, and browser settings. You can keep a separate profile per use case, like a LinkedIn profile or a GitHub profile. ### How do I create and reuse a profile across sessions? Create a session with `persistProfile: true`; after release, the profile reaches the `READY` state and the session returns a `profileId`. Pass that `profileId` when creating future sessions to start them with the same user data directory and context. # Clustering URL: https://docs.steel.dev/overview/self-hosting/clustering # Docker URL: https://docs.steel.dev/overview/self-hosting/docker # Overview This guide provides step-by-step instructions to set up your own Steel Browser instance using Docker. The setup consists of multiple deployment options – from the traditional docker-compose setup to the new, simplified single Docker image deployment. ## Prerequisites * Docker (20.10.0 or later) * At least 4GB of RAM * 10GB of free disk space ## Quick Start Using Docker Compose 1. Create a new directory for your Steel Browser instance: ```bash mkdir steel-browser && cd steel-browser ``` 2. Create the following file: ### docker-compose.yaml ```yaml services: api: image: ghcr.io/steel-dev/steel-browser-api:latest ports: - "3000:3000" - "9223:9223" volumes: - ./.cache:/app/.cache networks: - steel-network ui: image: ghcr.io/steel-dev/steel-browser-ui:latest ports: - "5173:80" depends_on: - api networks: - steel-network networks: steel-network: name: steel-network driver: bridge ``` 3. Launch the containers: ```bash docker compose up -d ``` 4. Access Steel Browser by opening `http://localhost:5173` in your web browser. ## Alternative Deployment: Single Docker Image Steel Browser can now be deployed using a single Docker image—no more complex docker-compose setup! ### Single Docker Image Deployment Run the following command to launch Steel Browser: ```bash docker run --rm -it -p 3000:3000 -p 9223:9223 ghcr.io/steel-dev/steel-browser:latest ``` This command will: - Pull the latest Docker image from GitHub Container Registry. - Expose the API on port 3000 and Chrome debugging on port 9223. - Run the container interactively and remove it when stopped. Access Steel Browser via your browser at `http://localhost:3000` and the UI at `http://localhost:3000/ui`. ## Building the Singular Docker Image Locally If you wish to build the Docker image from source rather than relying on the pre-built image, follow these steps: 1. Clone the repository: ```bash git clone https://github.com/steel-dev/steel-browser.git cd steel-browser ``` 2. Build the Docker image: ```bash docker build -t steel-browser:local . ``` 3. Run the newly built image: ```bash docker run --rm -it -p 3000:3000 -p 9223:9223 steel-browser:local ``` This method gives you the flexibility to modify the image locally. Compared to the docker-compose setup where the API and UI are managed in separate containers, here everything runs within one container, simplifying deployment for testing and development. ## Advanced Setup ### Building From Source with Docker Compose If you prefer to build the containers yourself with docker-compose: 1. Clone the repository: ```bash git clone https://github.com/steel-dev/steel-browser.git cd steel-browser ``` 2. Create a `.env` file (optional). 3. Build and start using the development compose file: ```bash docker compose -f docker-compose.dev.yml up -d --build ``` _The “-d” flag runs the containers in the background._ ### Configuration Options * **API Port**: Default is 3000 (internally also 3000). If changed in the compose file, update the API binding accordingly. * **UI Port**: Default is 5173 (or 80 inside container). Adjust if needed. * **Chrome Debugging Port**: Default is 9223. Required for browser communication. ### Volume Persistence The `.cache` directory stores Chrome data and extensions. Mount it as a volume for persistence: ```yaml volumes: - ./.cache:/app/.cache ``` ## Architecture Steel Browser consists of two main components when using docker-compose: 1. **API Container**: Runs Chrome in headless mode and provides CDP (Chrome DevTools Protocol) services. 2. **UI Container**: An Nginx-based frontend for interacting with the browser. When using the single Docker image deployment, both the API and UI are integrated into one container. ## Customizing the Build ### Using a Different Chrome Version The API container uses Chrome 128.0.6613.119 by default. To use a different version: 1. Create a custom Dockerfile based on the API one. 2. Modify the Chrome installation section: ```dockerfile ARG CHROME_VERSION="128.0.6613.119" RUN apt-get update && \ DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ wget \ ca-certificates \ curl \ unzip \ && CHROME_DEB="google-chrome-stable_${CHROME_VERSION}-1_amd64.deb" \ && wget -q "https://mirror.cs.uchicago.edu/google-chrome/pool/main/g/google-chrome-stable/${CHROME_DEB}" # ...rest of the installation... ``` ### Changing Node Version Both containers use Node 22.13.0 by default. To use a different version, modify the build arguments: ```yaml services: api: build: context: . dockerfile: ./api/Dockerfile args: NODE_VERSION: 18.19.0 ``` ## Troubleshooting ### Chrome Won't Start Ensure your host has enough resources and check the API container logs: ```bash docker logs steel-browser_api_1 ``` Common issues include: * Running on ARM architecture (There are official images for ARM, or build the image yourself) * Insufficient memory * Missing shared libraries * Permission issues with the `.cache` directory ### Connectivity Issues If the UI can't connect to the API: 1. Verify both containers are running. 2. Check if the API is accessible: ```bash curl http://localhost:3000/api/health ``` 3. Ensure the containers can communicate over the network: ```bash docker exec steel-browser_ui_1 curl http://api:3000/api/health ``` ## Production Deployment For production environments: 1. Use specific image versions rather than `latest`. 2. Set up a proper reverse proxy with HTTPS. 3. Configure appropriate resource limits. Example production compose file: ```yaml services: api: image: ghcr.io/steel-dev/steel-browser-api:sha256:... restart: always ports: - "3000:3000" deploy: resources: limits: memory: 2G volumes: - ./data/.cache:/app/.cache networks: - steel-network ui: image: ghcr.io/steel-dev/steel-browser-ui:sha256:... restart: always ports: - "5173:80" networks: - steel-network networks: steel-network: name: steel-network driver: bridge ``` ## Security Considerations * Avoid exposing the Chrome debugging port (9223) to the public internet. * Consider not exposing the API if the UI and API are running within the same secured network. * Set up proper authentication if deploying publicly. * Keep containers updated with the latest versions. ## Updating To update to the latest version: ```bash docker compose pull docker compose up -d ``` For custom builds: ```bash git pull docker compose -f docker-compose.dev.yml up -d --build ``` ### Need help running locally? Reach out to us on the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section. # Extensions URL: https://docs.steel.dev/overview/self-hosting/extensions # Profiles URL: https://docs.steel.dev/overview/self-hosting/profiles # Self-Host Steel Browser on Railway URL: https://docs.steel.dev/overview/self-hosting/railway [Deploy the Template on Railway ↗](https://railway.com/deploy/steelbrowser?referralCode=Jwc4kg&utm_medium=integration&utm_source=template&utm_campaign=generic) ### Overview Self-hosting Steel Browser on Railway provides a reliable, scalable environment for running headless Chrome instances. The Steel Browser API handles browser session management, proxy configuration, and CDP passthroughs while Railway provides extremely easy APIs to scale and handles resource allocation automatically. Running Steel Browser on Railway's infrastructure ensures your browser automations run consistently with minimal configuration, while providing automatic scaling and health monitoring for production workloads. ### Common Use Cases for Self-Hosted Steel Browser - **Web Scraping:** Extract data from dynamic websites that require JavaScript rendering - **Browser Automation:** Automate repetitive web tasks and workflows - **End-to-End Testing:** Run automated browser tests for web applications - **Screenshot & PDF Generation:** Capture screenshots or generate PDFs from web content - **Data Collection:** Gather information from multiple web sources programmatically ### Dependencies for Hosting Steel Browser - **Docker:** Steel Browser runs as a containerized application - **Chrome/Chromium:** Headless browser engine (included in the Docker image) - **Node.js Runtime:** Required for the Steel Browser service ### Deployment Dependencies - [Steel Browser GitHub Repository](https://github.com/steel-dev/steel-browser) - [Steel Browser Documentation](https://docs.steel.dev/) - [Chrome DevTools Protocol Documentation](https://chromedevtools.github.io/devtools-protocol/) ### Implementation Details **Steel Browser Health Check Endpoint:** Verify your Steel Browser instance is running: ```bash curl https://your-domain.railway.app/v1/health ``` **Connecting to Steel Browser:** After deployment, create a session and connect to your Steel Browser instance on the public domain using Playwright: ```typescript import { chromium } from "playwright"; import Steel from "steel-sdk"; const client = new Steel({ baseUrl: `https://${process.env.RAILWAY_PUBLIC_DOMAIN}`, }); session = await client.sessions.create(); browser = await chromium.connectOverCDP(session.websocketUrl); // The rest of your automation ``` ### Why Deploy Steel Browser on Railway? Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it. By deploying Steel Browser on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway. **Benefits of Steel Browser on Railway:** - Automatic HTTPS/SSL configuration - Built-in health monitoring - Easy scaling as your browser automation needs grow - Simple environment variable management - Seamless integration with other Railway services ### After Deploying Steel Browser After deploying this template, users should: 1. **Access Your Steel Instance:** Navigate to the Railway-provided public domain 2. **Verify Health:** Check the `/v1/health` endpoint returns a successful response 3. **Configure API Access:** Use the public domain URL in their application code 4. **Monitor Usage:** Check Railway's metrics dashboard for resource usage ### Securing Your Steel Browser Instance - Consider adding authentication if exposing publicly - Monitor for unusual traffic patterns - Set up rate limiting if needed for production use # Steel Local vs Steel Cloud URL: https://docs.steel.dev/overview/self-hosting/steel-local-vs-steel-cloud # Overview | Feature | Steel Local | Steel Cloud | |------------------|-------------------------------------------|--------------------------------------------------------------| | Concurrency | 1 | 100+ | | Stealth | Limited | Advanced Stealth (docs) | | Captcha Solving | None | Supported with the Captchas API | | Proxies | Bring your own | Bring your own + Steel Managed Proxies | | Multi-Region | Host it yourself | Supported with region flag during session creation | | Credentials | Not supported | Supported with the Credentials API | | Extensions | Supported by loading in `api/extensions/` | Supported by using the Extensions API | | Files | Not supported | Supported by the Files API | The defining factor between running Steel locally and using Steel Cloud is concurrency. For the Extensions API, if you put the extensions you would like to build/load in the `api/src/extensions/` folder then Steel Local will build these and inject them into the session. Credentials are not supported in Steel Local. ### Need help running locally? Reach out to us on the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section. ### FAQ ### Can I use proxies with self-hosted Steel? Yes — Steel Local supports bringing your own proxies. Steel Cloud additionally offers Steel-managed proxies on top of BYOP. ### Can I load browser extensions in Steel Local? Yes — put the extensions you want in the `api/src/extensions/` folder and Steel Local will build and inject them into the session. On Steel Cloud, extensions are loaded via the Extensions API instead. # WebRTC URL: https://docs.steel.dev/overview/self-hosting/webrtc # Configure a Browser Session URL: https://docs.steel.dev/overview/sessions-api/configuration 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 ```typescript import Steel from 'steel-sdk'; const client = new Steel({ steelAPIKey: process.env.STEEL_API_KEY, }); 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. | Task | Setting | Go to | |---|---|---| | Run standard browser automation | No optional setting | [Start with the minimum](#start-with-the-minimum) | | Release an idle session before `timeout` | `timeout`, `inactivityTimeout` | [Task with an inactivity timeout](#task-with-an-inactivity-timeout) | | Run a longer headless task and release it when idle | Headless and session life settings | [Long-running headless worker](#long-running-headless-worker) | | Extract text from a protected site | Proxy, CAPTCHA, and resource settings | [Text extraction on a protected site](#text-extraction-on-a-protected-site) | | Detect a CAPTCHA and let a person respond | CAPTCHA and interactive viewer settings | [CAPTCHA detection with human control](#captcha-detection-with-human-control) | | Use stored account state without saving changes | `profileId` | [Account task without saved changes](#account-task-without-saved-changes) | | Repeat an account task with one identity | Profile and dedicated IP settings | [Account task with stored state](#account-task-with-stored-state) | | Open a mobile site from a selected country | Device and proxy settings | [Mobile task in a selected country](#mobile-task-in-a-selected-country) | ### Find a setting If you know the browser behavior that the task needs, use this table. | Requirement | Setting | Go to | |---|---|---| | Use a residential IP | `useProxy: true` | [Network identity](#network-identity) | | Select the IP location | `useProxy.geolocation` | [Network identity](#network-identity) | | Use the same dedicated IP | `useProxy: { type: "fixed", id: "fixed:…" }` | [Network identity](#network-identity) | | Run the browser in a selected region | `region` | [Network identity](#network-identity) | | Load saved browser state | `profileId` | [Stored state](#stored-state) | | Save profile changes after release | `persistProfile: true` | [Stored state](#stored-state) | | Add cookies or web storage | `sessionContext` | [Stored state](#stored-state) | | Use credentials that Steel stores | `credentials` | [Stored state](#stored-state) | | Detect or solve CAPTCHAs | `solveCaptcha` | [Page support](#page-support) | | Let a person control the browser | `debugConfig.interactive: true` | [Viewer and connection](#viewer-and-connection) | | Make the viewer read-only | `debugConfig.interactive: false` | [Viewer and connection](#viewer-and-connection) | | Connect with Selenium | `isSelenium: true` | [Viewer and connection](#viewer-and-connection) | | Block page resources | `optimizeBandwidth` | [Resource control](#resource-control) | | Load browser extensions | `extensionIds` | [Resource control](#resource-control) | | Set the browser window size | `dimensions` | [Browser interface](#browser-interface) | | Use fullscreen mode | `fullscreen: true` | [Browser interface](#browser-interface) | | Select the project context | `projectId`, `namespace` | [Project context](#project-context) | `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. ```bash curl https://api.steel.dev/v1/sessions \ -H "steel-api-key: $STEEL_API_KEY" \ -H "Content-Type: application/json" \ -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. ```json { "timeout": 600000, "inactivityTimeout": 60000 } ``` 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. ```json { "headless": true, "timeout": 900000, "inactivityTimeout": 120000 } ``` 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. ```json { "useProxy": true, "solveCaptcha": true, "optimizeBandwidth": { "blockImages": true, "blockMedia": true, "blockStylesheets": false } } ``` 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. ```json { "solveCaptcha": true, "stealthConfig": { "autoCaptchaSolving": false }, "debugConfig": { "interactive": true } } ``` 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. ```json { "profileId": "123e4567-e89b-12d3-a456-426614174000" } ``` 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. ```json { "profileId": "123e4567-e89b-12d3-a456-426614174000", "persistProfile": true, "useProxy": { "type": "fixed", "id": "fixed:8SdfYs77me" } } ``` 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. ```json { "deviceConfig": { "device": "mobile" }, "useProxy": { "geolocation": { "country": "DE" } } } ``` 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](#find-a-setting) to open a section. ### Session life Use these settings to control the total and idle session life. | Setting | Guidance | |---|---| | `timeout` | Sets the requested maximum session life. The default is 300000 ms (5 minutes). Set the value to 15000 ms or more. Your account limits set the maximum permitted value. | | `inactivityTimeout` | Releases an idle session before `timeout`. Set the value below `timeout`. If your SDK type does not include this field, use the REST API. | CDP commands and remote input reset the inactivity timer. After the task is complete, release the session. See [Session Lifecycle](/overview/sessions-api/session-lifecycle) for session states and release methods. ### Network identity Use the smallest location scope that the task needs. | Requirement | Configuration | |---|---| | Use the browser machine IP | Set `useProxy` to `false`. Omit `proxyUrl`. | | Use a residential IP | Set `useProxy` to `true`. | | Select a country, state, or city | Set `useProxy.geolocation`. Include a country. | | Use one dedicated IP | Set `useProxy.type` to `fixed` and add the dedicated IP `id`. | | Use any active dedicated IP | Set `useProxy.type` to `fixed` and omit `id`. | | Use your proxy | Set `useProxy.server` or `proxyUrl`. | | Select the browser region | Set `region`. | - `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](/overview/sessions-api/multi-region), [Proxies](/overview/stealth/proxies), and [Dedicated IPs](/overview/sessions-api/dedicated-ips). ### Stored state Select the state methods that the task needs. | Available state | Method | |---|---| | A specific set of cookies or web storage | Use `sessionContext`. | | Browser state that must change across sessions | Use a profile. | | Credentials that Steel stores | Add a `credentials` object. | 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. Copy `profileId` from the first session response. 2. Complete the browser task. 3. Release the first session. 4. Wait until the profile status is `READY`. 5. Create the next session with `profileId`. 6. If 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](/overview/profiles-api/overview), [Reusing Auth Context](/overview/sessions-api/reusing-auth-context), and [Credentials](/overview/credentials-api/overview). ### Browser interface Use these settings to select the window size, mobile identity, or display mode. | Requirement | Configuration | |---|---| | Set the browser window size | Set `dimensions`. | | Use a mobile browser identity | Set `deviceConfig.device` to `"mobile"`. If the request and profile omit `dimensions`, Steel uses 508×1074. | | Fill the browser screen | Set `fullscreen` to `true`. Fullscreen mode uses 1920×1080 and ignores `dimensions`. | | Set a specific user agent | Set `userAgent`. | Steel rejects custom mobile dimensions below 508×1074 (width × height). Use mobile mode for a complete mobile browser identity. See [Mobile Mode](/overview/sessions-api/mobile-mode) and [Fullscreen Mode](/overview/sessions-api/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: ```json { "solveCaptcha": true, "stealthConfig": { "autoCaptchaSolving": false } } ``` - 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](/overview/captchas-api/overview) 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. | Requirement | Configuration | |---|---| | Block ads | Set `blockAds` to `true`. | | Block images, media, and stylesheets | Set `optimizeBandwidth` to `true`. | | Select resource types, hosts, or URL patterns | Set `optimizeBandwidth` to an object. | | Load uploaded extensions | Set `extensionIds` to the uploaded extension IDs. See [Extensions](/overview/extensions-api/overview) for extension management. | 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. | Requirement | Configuration | |---|---| | Allow input from the live viewer | Set `debugConfig.interactive` to `true`. This is the default. | | Make the live viewer read-only | Set `debugConfig.interactive` to `false`, or add `interactive=false` to the viewer URL. | | Show the system cursor in a headful stream | Set `debugConfig.systemCursor` to `true`. This is the default and does not control viewer input. | | Use a headless browser | Set `headless` to `true`. | | Connect with Selenium | Set `isSelenium` to `true`. This forces `headless` to `true`, even if the request sets `headless` to `false`. | The viewer URL cannot make a read-only session interactive. ### Protect the debug URL Anyone with the debug URL can view the session and control an interactive session. Before you share the debug URL, add application access controls. See [Live Sessions](/overview/sessions-api/embed-sessions/live-sessions), [Human-in-the-Loop Controls](/overview/sessions-api/human-in-the-loop), and [Selenium](/integrations/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](/api-reference#tag/sessions). # Dedicated IPs URL: https://docs.steel.dev/overview/sessions-api/dedicated-ips Steel sessions give you a fresh cloud browser on demand. Dedicated IPs let those sessions look consistent where the network matters. Without a dedicated IP, each session may come from a different network path. With a dedicated IP, a site can see requests from a familiar IP instead of a new location on every run. This is useful for login reliability, long-running automations, and workflows where repeated "new network" signals cause extra checks. This is often called the impossible traveler problem: auth and anti-bot systems see the same account appear from unrelated networks or locations too quickly, then invalidate the saved auth state or add extra verification. Profiles take this further. A dedicated IP gives the session stable network identity, but it does not preserve the browser itself. Without a profile, each session still starts like a new browser: no cookies, local storage, IndexedDB, login state, permissions, or prior browser history. With [Steel Profiles](/overview/profiles-api/overview), the browser identity persists too. You can sign in once, release the session, and later start another cloud browser with the same profile and the same saved browser state. Together: - Sessions give you scalable, on-demand cloud browsers. - Dedicated IPs give those sessions stable network identity. - Profiles give those sessions stable browser identity. - Using both helps automations resume from a trusted, logged-in state instead of starting cold every time. ## Lease Dedicated IPs Dedicated IPs are leased from **Settings > Network** in the Steel dashboard. They are available on paid plans; Hobby workspaces need to upgrade before leasing dedicated IPs. Each dedicated IP is billed as a monthly subscription at **$5 per dedicated IP / month**. You can lease up to 25 dedicated IPs self-serve from the Network page. If you need more, contact support. 1. Open [Settings > Network](https://app.steel.dev/settings/network). 2. Click **Lease Dedicated IPs**. 3. Choose a location and quantity. 4. Complete checkout. After checkout completes, the Network page lists each leased dedicated IP. You will see the public IP address, such as `203.0.113.42`, and a Steel dedicated IP identifier, such as `fixed:8SdfYs77me`. Use the `fixed:` identifier in API requests. Copy the Dedicated IP ID from the Network page when you want to pin a session or profile to a specific IP. ## Use Any Dedicated IP Pass `useProxy: { type: "fixed" }` when creating a session. Steel will randomly select one active dedicated IP from your workspace. ```typescript const session = await client.sessions.create({ useProxy: { type: "fixed" }, }); ``` ```python session = client.sessions.create( use_proxy={"type": "fixed"} ) ``` This default is useful when you want stable, dedicated egress without caring which dedicated IP is used for a specific run. ## Pin A Specific Dedicated IP If you want a specific IP, pass its fixed IP identifier with `id`. ```typescript const session = await client.sessions.create({ useProxy: { type: "fixed", id: "fixed:aaaa" }, }); ``` ```python session = client.sessions.create( use_proxy={"type": "fixed", "id": "fixed:aaaa"} ) ``` Use this when a specific account, profile, customer, or workflow should always use the same network identity. ## Persist A Dedicated IP With A Profile When you create a persisted profile with an unspecified dedicated IP, Steel first selects one of your dedicated IPs, then stores that selected IP on the profile after the session starts successfully. ```typescript const firstSession = await client.sessions.create({ persistProfile: true, useProxy: { type: "fixed" }, }); const profileId = firstSession.profileId; const secondSession = await client.sessions.create({ profileId, }); ``` ```python first_session = client.sessions.create( persist_profile=True, use_proxy={"type": "fixed"} ) profile_id = first_session.profile_id second_session = client.sessions.create( profile_id=profile_id ) ``` The second session loads the saved profile, including the fixed IP selection. That means future sessions using the profile can keep both the same browser state and the same network identity. You can also explicitly pin the IP at profile creation time: ```typescript const session = await client.sessions.create({ persistProfile: true, useProxy: { type: "fixed", id: "fixed:aaaa" }, }); ``` ```python session = client.sessions.create( persist_profile=True, use_proxy={"type": "fixed", "id": "fixed:aaaa"} ) ``` ## Why Lease Multiple IPs? Multiple dedicated IPs give you more control over how work is distributed: - Keep one stable IP per account, profile, customer, or workflow. - Run parallel sessions without every workflow sharing the same IP. - Reduce repeated traffic from one network identity. - Keep a fallback IP available if a site challenges or blocks one IP. - Let Steel randomly distribute sessions across your dedicated IPs when you do not pass an `id`. For account-based automations, a common pattern is one profile plus one dedicated IP per account. The profile keeps browser state. The dedicated IP keeps network identity. ## Billing And Metering Dedicated IP traffic is metered as normal proxy bandwidth. It appears in the same proxy bandwidth usage model as your other Steel proxy traffic. Browser session time is still metered separately as normal session usage. ### Need help choosing an IP strategy? Reach out to us on the **#help** channel on [Discord](https://discord.gg/steel-dev) under the ⭐ community section. ## FAQ ### What happens if I do not pass a fixed IP `id`? Steel randomly selects one active dedicated IP from your workspace. If you use a persisted profile, Steel saves that selected IP to the profile after the session starts. ### Should I use dedicated IPs with profiles? Yes, if the workflow needs continuity. Dedicated IPs keep the network identity stable. Profiles keep cookies, storage, login state, permissions, and browser history stable. ### Does dedicated IP traffic have separate metering? No. Dedicated IP traffic counts as normal proxy bandwidth. Browser session time is still metered separately. # Fullscreen Mode URL: https://docs.steel.dev/overview/sessions-api/fullscreen-mode ### Overview Fullscreen mode launches the browser covering the full screen with no Chrome UI—no address bar, no tabs, no toolbars. Pass `fullscreen: true` when creating a session and the page gets every pixel of the 1920×1080 screen. By default, sessions run windowed: Steel reserves space for browser UI the same way a real desktop browser does, so the page sees a viewport slightly smaller than the screen. Fullscreen removes that reservation entirely. The result is cleaner screenshots and recordings with no browser chrome in the frame, and a viewport that exactly matches the screen. ### How It Works ```typescript import Steel from 'steel-sdk'; import { chromium } from 'playwright'; const client = new Steel({ steelAPIKey: process.env.STEEL_API_KEY }); // Create a session that launches fullscreen const session = await client.sessions.create({ fullscreen: true }); // Connect to the fullscreen session const browser = await chromium.connectOverCDP( `wss://connect.steel.dev?apiKey=${process.env.STEEL_API_KEY}&sessionId=${session.id}` ); const page = await browser.contexts()[0].pages()[0]; await page.goto('https://example.com'); ``` ```python from steel import Steel from playwright.async_api import async_playwright import os client = Steel(steel_api_key=os.environ.get("STEEL_API_KEY")) # Create a session that launches fullscreen session = client.sessions.create( fullscreen=True ) # Connect to the fullscreen session async with async_playwright() as p: browser = await p.chromium.connect_over_cdp( f"wss://connect.steel.dev?apiKey={os.environ.get('STEEL_API_KEY')}&sessionId={session.id}" ) page = browser.contexts[0].pages[0] await page.goto('https://example.com') ``` The flag is set at session creation and can't be changed on a running session. It defaults to `false`, so existing integrations are unaffected, and it echoes back on the session object so you can confirm what you got. The difference fullscreen makes is in the viewport. A windowed session subtracts a chrome allowance from the screen—5px of width and 91px of height—so a default 1920×1080 session hands the page a 1915×989 viewport. Fullscreen skips the subtraction: | | Windowed (default) | Fullscreen | |---|---|---| | Browser UI | Reserves space at the top | None | | Screen size | Your `dimensions`, capped at 1920×1080 | Fixed at 1920×1080 | | Viewport | Screen minus chrome allowance (e.g. 1915×989) | Full 1920×1080 | | `innerHeight` vs `screen.height` | Smaller | Identical | ### Why This Matters **Clean Screenshots and Recordings** No browser UI means no strip of dead pixels at the top of every capture. Screenshots and session recordings show only page content, with no cropping step in your pipeline. **Kiosk-Style Displays** Dashboards, signage, and embedded views render edge-to-edge, the way they would on a dedicated full-screen display. Pages built against the full viewport get the canvas they expect. **Watch-Only Views for Your Users** Pair fullscreen with a read-only embed and you can surface a live session inside your own product as a clean, edge-to-edge view your users can watch but not control. Embed the session's `debugUrl` with `interactive=false` to lock interaction to your backend, and fullscreen removes the browser chrome so all they see is the page. See [Live Sessions](/overview/sessions-api/embed-sessions/live-sessions) for the embed parameters. **Viewport Matches Screen** Sites that compare `innerHeight` to `screen.height` see exactly what a maximized, fullscreened real browser reports: the two are identical. Windowed sessions report the gap a real toolbar would create, so both modes present a consistent fingerprint—fullscreen just presents the edge-to-edge one. ### Things to Know - **Fullscreen overrides `dimensions`.** The session is fixed at 1920×1080; any `width`/`height` you pass is ignored. Use `dimensions` for a specific size, `fullscreen` for the whole screen—not both. - **Click coordinates shift.** Moving from a windowed session to fullscreen changes the viewport from 1915×989 to 1920×1080, so saved coordinates from windowed runs won't line up. - **It's not the viewer's fullscreen button.** That button expands the live viewer on your screen; `fullscreen: true` changes how the cloud browser itself launches. ### Need help with fullscreen mode? Reach out to us on the **#help** channel on [Discord](https://discord.gg/steel-dev) or [@steeldotdev](https://twitter.com/steeldotdev). # Implement Human-in-the-Loop Controls URL: https://docs.steel.dev/overview/sessions-api/human-in-the-loop Steel's debug URL feature allows you to implement human-in-the-loop workflows where users can directly interact with and control browser sessions. This is particularly useful when you need users to take temporary control of automated browser sessions. ### Prerequisites * Basic familiarity with [Steel sessions](https://docs.steel.dev/overview/sessions-api/overview) * Understanding of [debug URLs](https://docs.steel.dev/overview/sessions-api/embed-sessions/live-sessions) * A Steel API key ### Making Sessions Interactive To enable human interaction with a session, you'll need to configure two key parameters when embedding the session viewer: * `interactive=true`: Enables users to interact with the page through clicks, scrolling, and form inputs * `showControls=true`: Shows the navigation bar where users can enter URLs and use forward/back controls ```typescript ``` When both parameters are enabled, users can: * Click and interact with elements on the page * Scroll the page * Enter new URLs in the navigation bar * Use browser-style forward/back navigation * Fill out forms and input fields * Navigate through websites naturally If you’re building user facing agents, this is particularly useful when you need users to: * Take control of an automated session that needs assistance * Enter sensitive information like login credentials * Solve CAPTCHAs * Verify or correct automated actions * Demonstrate actions that will be automated ### Implementation Examples #### React Implementation Here's how to embed an interactive session viewer into a React Application: ```typescript // SessionViewer.tsx import React from 'react'; type SessionViewerProps = { debugURL: string; }; const SessionViewer: React.FC = ({ debugURL }) => { return (

Automated session - Click inside to take control

``` - Streams real-time browser output using **WebRTC + H.264** - Works in all major browsers with baseline H.264 support - `interactive=true` allows remote mouse/keyboard input for collaborative debugging or human-in-the-loop workflows > **Note:** For security reasons, debug URLs are **unauthenticated**. > Anyone with the debug URL can view or interact with that session. > Use your own-access controls if embedding in a user-facing product. --- ### Supported Parameters (Headful) | Parameter | Type | Default | Description | |------------|------|----------|-------------| | `interactive` | boolean | `true` | Enables or disables remote control of the live session. | Example: ```html ``` Disabling interactivity makes the view read-only, ideal for watch-only monitoring scenarios. --- ## Headless (Legacy) > Headless live sessions remain supported for existing workflows. > They use Chrome’s screencasting instead of WebRTC and expose additional configuration options. ### Configuration Options (Headless Only) | Parameter | Type | Default | Description | |------------|------|----------|-------------| | `theme` | string | `"dark"` | UI theme (`dark` or `light`) | | `interactive` | boolean | `true` | Enable or disable interaction | | `showControls` | boolean | `true` | Show or hide navigation UI | | `pageId` | string | (empty) | Focus the view on a specific page/tab | | `pageIndex` | string | (empty) | Display a specific tab by index | Example: ```html ``` --- ### Common Use Cases **Read-only viewer** ```html ``` **Human-in-the-loop control** Allow humans to take over automation tasks or debug live workflows interactively using `interactive=true`. --- ### Troubleshooting If the embedded view appears blank or unresponsive: - Ensure the session is active (default timeout: 5 min). - Confirm your browser supports **H.264 baseline** playback. - Check your container has fixed dimensions (`width` and `height`). - Verify the correct session and valid API key were used. --- ### Summary All new sessions now run **headful by default**, streaming real-time video with WebRTC. Use the same `debugUrl` to embed or view — Steel automatically determines the correct playback mode. Headless live streams remain available for legacy sessions but will be phased out over time. ### FAQ ### Can I embed a live Steel browser session in my app? Yes. Every session created via the API returns a `debugUrl` that you can open directly in a browser or embed in your UI with an iframe, streaming the live browser in real time. ### Can users interact with an embedded live session, or is it view-only? Both. The `interactive` parameter (default `true`) enables remote mouse and keyboard input for human-in-the-loop workflows; set `interactive=false` on the debug URL for a read-only, watch-only view. ### Is the debug URL authenticated? No. Debug URLs are unauthenticated by design, so anyone with the URL can view or interact with that session. Add your own access controls if you embed live sessions in a user-facing product. ### How does Steel's live view streaming work? New sessions run headful by default and stream real-time video over WebRTC at 25 fps using H.264, with OS-level capture and low latency. Legacy headless sessions use the same `debugUrl` but display via Chrome's screencasting, and Steel automatically picks the right playback mode. # Past Sessions URL: https://docs.steel.dev/overview/sessions-api/embed-sessions/past-sessions Steel automatically records every session so you can replay it later. With the new headful session recordings, you can now embed real MP4 playback — no event reconstruction, no missing UI elements. For older implementations, we still support headless playback via rrweb. ## Embed Headful Session Recordings (Recommended) ### What Changed Steel has moved from slow, unreliable screencasting and event-based playback to full OS-level streaming and MP4 recordings. - 25fps WebRTC-based video streaming - MP4 recordings showing the exact screen output - No discrepancies between actual sessions and replays > **Tip:** Headful sessions are now **default** for all Steel sessions. > No changes are needed to your integration — this gives you direct control over embedding playback. ### Retrieving the Recording Playlist ```typescript const playlist = await fetch("https://api.steel.dev/v1/sessions/{session_id}/hls", { headers: { "steel-api-key": "YOUR_API_KEY" } }); ``` ```python import requests url = "https://api.steel.dev/v1/sessions/{session_id}/hls" headers = { "steel-api-key": "YOUR_API_KEY" } response = requests.get(url, headers=headers) playlist = response.text ``` This returns an HLS playlist that can be used in any compatible video player. ### Embedding in a Web Page ```html

``` **Notes:** - Works with any HLS-compatible player (e.g., Safari, HLS.js, JW Player, Video.js). - Recordings are durable MP4 streams for accurate, 1:1 playback. ## Headless > Headless playback is supported for legacy sessions. > New sessions use headful replays for full visual fidelity — we recommend migrating when possible. ### Overview Every Steel browser session records page events. You can fetch those events from the `/v1/sessions/:id/events` endpoint and replay them using `rrweb-player`. ### Retrieve the Recorded Events **SDK Example** ```ts const events = await client.sessions.events(session.id); ``` or ```python events = client.sessions.events(session_id=session.id) ``` **Direct API** ```text GET /v1/sessions/:id/events ``` ### Replay with rrweb-player **Install** ```bash npm install rrweb-player ``` **Usage** ```ts import rrwebPlayer from "rrweb-player"; import "rrweb-player/dist/style.css"; const events = await client.sessions.events(session.id); const playerElement = document.getElementById("player-container"); new rrwebPlayer({ target: playerElement, props: { events: events, width: 800, height: 600, autoPlay: true, skipInactive: true } }); ``` **HTML** ```html

``` --- ### Summary All new sessions now run **headful by default**. Headless event-based playback remains available for legacy recordings but will be deprecated in the future. Use headful recordings for the most accurate, reliable replays. # Available Skills URL: https://docs.steel.dev/overview/skills/available-skills ## Install commands ```bash npx skills add steel-dev/skills --skill steel-browser npx skills add steel-dev/skills --skill steel-developer npx skills add steel-dev/skills --skill steel-session-debugging npx skills add steel-dev/skills --skill steel-reliability npx skills add steel-dev/skills --skill steel-skill-creator ``` For Claude Code plugin installs, add the marketplace once and install by skill name: ```bash /plugin marketplace add steel-dev/skills /plugin install steel-browser@steel-skills ``` ## Choosing a skill | Intent | Primary Skill | | ---------------------------------------------------------------------- | ------------------------- | | Browse, click, scrape, screenshot, or create a PDF now | `steel-browser` | | Write reusable Steel code | `steel-developer` | | Diagnose a failed session | `steel-session-debugging` | | Mitigate bot detection, CAPTCHA, proxy, identity, or login reliability | `steel-reliability` | | Turn a recurring browser task into a reusable workflow | `steel-skill-creator` | # Steel Browser Skill URL: https://docs.steel.dev/overview/skills/available-skills/steel-browser ## Install ```bash npx skills add steel-dev/skills --skill steel-browser ``` After adding the Steel Skills marketplace in Claude Code: ```bash /plugin install steel-browser@steel-skills ``` ## Use When - The agent should visit a page now. - WebFetch or curl is insufficient. - The task needs JavaScript, forms, login, screenshots, PDFs, or multi-step navigation. ## Example Prompts - "Use Steel to open example.com and summarize the page." - "Fill out this form in a Steel browser and show me the result." - "Take a full-page screenshot of this dashboard." ## Related Skills - Use `steel-developer` for reusable Steel code. - Use `steel-session-debugging` if a live session fails. - Use `steel-reliability` if evidence points to bot detection, CAPTCHA, proxy, or login reliability. # Steel Developer Skill URL: https://docs.steel.dev/overview/skills/available-skills/steel-developer ## Install ```bash npx skills add steel-dev/skills --skill steel-developer ``` After adding the Steel Skills marketplace in Claude Code: ```bash /plugin install steel-developer@steel-skills ``` ## Use When - The user wants SDK, REST API, Playwright, Puppeteer, Stagehand, or Browser Use code. - The user is building an app on Steel. - The task involves credentials, profiles, files, extensions, live embeds, traces, or computer-use integrations. ## Example Prompts - "Write a TypeScript Playwright script that runs on Steel." - "Show how to upload a file into a Steel session and submit it." - "Build a UI that embeds a live Steel session viewer." ## Related Skills - Use `steel-browser` for live web work now. - Use `steel-session-debugging` for failed-session diagnosis. - Use `steel-reliability` for bot/proxy/CAPTCHA/login mitigation. # Steel Reliability Skill URL: https://docs.steel.dev/overview/skills/available-skills/steel-reliability ## Install ```bash npx skills add steel-dev/skills --skill steel-reliability ``` After adding the Steel Skills marketplace in Claude Code: ```bash /plugin install steel-reliability@steel-skills ``` ## Use When - The site returns 403, access denied, verify-human pages, or redirect loops. - CAPTCHA solving fails or loops. - Steel-managed proxy or BYOP proxy behavior needs diagnosis. - Login state, profiles, credentials, identity, pacing, or retry policy affects success. ## Example Prompts - "Plan the least invasive mitigation for this 403." - "Show me the safe BYOP pattern on Hobby." - "Should this login workflow use profiles, credentials, or both?" ## Related Skills Use `steel-session-debugging` first when the failure class is unknown or you need logs, traces, replay links, or screenshots. # Steel Session Debugging Skill URL: https://docs.steel.dev/overview/skills/available-skills/steel-session-debugging ## Install ```bash npx skills add steel-dev/skills --skill steel-session-debugging ``` After adding the Steel Skills marketplace in Claude Code: ```bash /plugin install steel-session-debugging@steel-skills ``` ## Use When - A Steel session failed, timed out, stalled, or produced unexpected output. - The user provides a session ID, replay, screenshot, log snippet, or failure report. - The agent needs evidence before recommending a fix. ## Example Prompts - "Debug why Steel session `sess_123` failed after login." - "Use the traces and logs to explain what happened in this run." - "Classify this failure and tell me the next verification step." ## Related Skills Use `steel-reliability` after evidence collection when the fix is bot detection, CAPTCHA, proxy, profile identity, login persistence, pacing, or retry strategy. # Steel Skill Creator URL: https://docs.steel.dev/overview/skills/available-skills/steel-skill-creator ## Install ```bash npx skills add steel-dev/skills --skill steel-skill-creator ``` After adding the Steel Skills marketplace in Claude Code: ```bash /plugin install steel-skill-creator@steel-skills ``` ## Use When - A user repeats the same browser task. - The task has clear inputs and success criteria. - The agent can safely record the task twice in Steel. - You want a repeatable workflow the agent can run again later. ## Example Prompts - "Turn this weekly report download into a reusable workflow." - "Capture this search workflow twice and make it parameterized." - "Package this repeated browser task so my agent can run it again next week." ## Related Skills Use `steel-browser` to drive the recording sessions, `steel-session-debugging` for failed recordings, and `steel-reliability` for bot/proxy/CAPTCHA reliability issues.