Build your first Steel automation
In this tutorial, you build a small automation, one step at a time. It signs in to a practice website and reads a page that only a signed-in user can see. Then it keeps the sign-in, so that its next run starts signed in. At the end, you review a finished run.
Each step adds one part of a Steel automation:
- A session: a browser that Steel runs for you in the cloud. You watch it live.
- Playwright, which drives the session's browser.
- A profile, which keeps the browser's cookies from one session to the next.
- The session's details and its recording, which stay after the session ends.
You write the automation in TypeScript or Python. To let a coding agent drive the browser instead, start with Set up your agent.
Before you begin
You need:
- A Steel account. Sign up at app.steel.dev.
- An API key. Create one in API Keys and put it in the
STEEL_API_KEYenvironment variable. - Node.js 20 or later, or Python 3.10 or later.
Make a folder for the project, and install the Steel SDK and Playwright in it:
mkdir first-automation
cd first-automation
npm install steel-sdk playwrightmkdir first-automation
cd first-automation
python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwrightIn Python, the commands make a virtual environment, so that python runs the Python that has the SDK. In each new terminal, run source .venv/bin/activate again.
The browser runs in Steel, so you do not run playwright install.
The automation signs in to Steel's practice site, a set of pages for practicing browser automation. Its sign-in page shows a demo account, tomsmith with the password SuperSecretPassword!. The code has them in plain text, because the site shows them to everyone. For your own site, keep the password out of the code. Read it from an environment variable, or let Steel fill it in with credentials.
1. Start a session and watch it live
A session is one browser that Steel runs for you. You pay for a session until it ends, so the program ends it when it is done.
Save this program as automation.mts or automation.py:
import { createInterface } from "node:readline/promises";
import Steel from "steel-sdk";
const client = new Steel();
const session = await client.sessions.create();
console.log(`Session ${session.id}`);
console.log(`Watch it live at ${session.sessionViewerUrl}`);
try {
if (process.stdin.isTTY) {
const prompt = createInterface({ input: process.stdin, output: process.stdout });
await prompt.question("Open the URL, then press Enter.");
prompt.close();
}
} finally {
const released = await client.sessions.release(session.id);
console.log(released.message);
}import sys
from steel import Steel
client = Steel()
session = client.sessions.create()
print(f"Session {session.id}")
print(f"Watch it live at {session.session_viewer_url}")
try:
if sys.stdin.isatty():
input("Open the URL, then press Enter.")
finally:
released = client.sessions.release(session.id)
print(released.message)sessions.create starts the session. The program prints the session's ID and its sessionViewerUrl, the session's page in the Steel dashboard. Then it waits for you. When you press Enter, the finally block releases the session. The block runs even when a line before it fails, so the session always ends. When the program runs without a terminal, for example when a coding agent runs it, it does not wait.
Run the program:
npx tsx automation.mtspython automation.pyIt prints the session's ID and the URL, then waits:
Session 3141760e-c26e-4d1e-bd15-2b1799d54fb0
Watch it live at https://app.steel.dev/sessions/3141760e-c26e-4d1e-bd15-2b1799d54fb0
Open the URL, then press Enter.Open the URL in a browser where you are signed in to Steel. The viewer shows the session's browser, live. Live view explains what else it can do. Press Enter. The program releases the session:
Session released successfully.2. Sign in to the site
Now the program drives the browser with Playwright. Playwright connects to the session's websocketUrl over the Chrome DevTools Protocol (CDP). The URL holds a token for the session, so Playwright needs no API key. CDP explains the URL.
Replace the program in automation.mts or automation.py with this one. It still waits for Enter, and then it signs in, so that you can watch the sign-in live:
import { createInterface } from "node:readline/promises";
import { chromium } from "playwright";
import Steel from "steel-sdk";
const client = new Steel();
const session = await client.sessions.create();
console.log(`Session ${session.id}`);
console.log(`Watch it live at ${session.sessionViewerUrl}`);
try {
if (process.stdin.isTTY) {
const prompt = createInterface({ input: process.stdin, output: process.stdout });
await prompt.question("Open the URL, then press Enter.");
prompt.close();
}
const browser = await chromium.connectOverCDP(session.websocketUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://steel.dev/practice/login");
await page.getByLabel("Username").fill("tomsmith");
await page.getByLabel("Password").fill("SuperSecretPassword!");
await page.getByRole("button", { name: "Login" }).click();
await page.waitForURL("https://steel.dev/practice/secure");
console.log(await page.locator("h4").innerText());
await browser.close();
} finally {
const released = await client.sessions.release(session.id);
console.log(released.message);
}import sys
from playwright.sync_api import sync_playwright
from steel import Steel
client = Steel()
session = client.sessions.create()
print(f"Session {session.id}")
print(f"Watch it live at {session.session_viewer_url}")
try:
if sys.stdin.isatty():
input("Open the URL, then press Enter.")
with sync_playwright() as playwright:
browser = playwright.chromium.connect_over_cdp(session.websocket_url)
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
page.goto("https://steel.dev/practice/login")
page.get_by_label("Username").fill("tomsmith")
page.get_by_label("Password").fill("SuperSecretPassword!")
page.get_by_role("button", name="Login").click()
page.wait_for_url("https://steel.dev/practice/secure")
print(page.locator("h4").inner_text())
browser.close()
finally:
released = client.sessions.release(session.id)
print(released.message)After you press Enter, the program:
- Connects Playwright to the session, and uses the page that the browser already has open. Use the session's context explains why it does not open a new one.
- Opens the sign-in page, fills in the two fields, and clicks Login.
getByLabel(get_by_labelin Python) finds a field by its label.getByRole(get_by_role) finds the button by its role and its name. - Waits until the browser reaches the secure area. The site opens it only after a sign-in that worked.
- Prints the text of the page's
h4heading, which only a signed-in user sees.
Run the program, open the URL, and press Enter. In the viewer, the browser fills in the form and opens the secure area. The program prints the text of the heading:
Session a1fda95c-d91b-4d45-aefe-153c9f72e19f
Watch it live at https://app.steel.dev/sessions/a1fda95c-d91b-4d45-aefe-153c9f72e19f
Open the URL, then press Enter.
Welcome to the Secure Area. When you are done click logout below.
Session released successfully.3. Keep the sign-in for the next run
Each session starts as a new browser with no cookies, so each run of the program signs in again. A profile keeps the browser's cookies and storage from one session to the next, so a later run starts signed in.
Make three changes to the program:
- Create the session with
persistProfile: true. When you release the session, Steel saves the browser to a profile. When thePROFILE_IDenvironment variable holds a profile's ID, the session also gets it asprofileId, and starts from that profile. Without aprofileId, Steel creates a new profile. - Open the secure area first. If the browser is still signed in, the site shows the secure area. If not, the site sends the browser to the sign-in page, and the program signs in.
- After the release, wait until the profile is
READY, and print its ID.
import { createInterface } from "node:readline/promises";
import { chromium } from "playwright";
import Steel from "steel-sdk";
const client = new Steel();
const session = await client.sessions.create({
profileId: process.env.PROFILE_ID,
persistProfile: true,
});
console.log(`Session ${session.id}`);
console.log(`Watch it live at ${session.sessionViewerUrl}`);
try {
if (process.stdin.isTTY) {
const prompt = createInterface({ input: process.stdin, output: process.stdout });
await prompt.question("Open the URL, then press Enter.");
prompt.close();
}
const browser = await chromium.connectOverCDP(session.websocketUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
const secure = "https://steel.dev/practice/secure";
await page.goto(secure);
if (page.url() === secure) {
console.log("Already signed in");
} else {
await page.getByLabel("Username").fill("tomsmith");
await page.getByLabel("Password").fill("SuperSecretPassword!");
await page.getByRole("button", { name: "Login" }).click();
await page.waitForURL(secure);
console.log("Signed in");
}
console.log(await page.locator("h4").innerText());
await browser.close();
} finally {
const released = await client.sessions.release(session.id);
console.log(released.message);
}
async function waitUntilReady(profileId: string) {
const deadline = Date.now() + 60_000;
for (;;) {
const profile = await client.profiles.get(profileId);
if (profile.status === "READY") return profile;
if (profile.status === "FAILED") throw new Error(`Steel could not save profile ${profileId}.`);
if (Date.now() > deadline) throw new Error(`Profile ${profileId} is not ready after 60 seconds.`);
await new Promise((resolve) => setTimeout(resolve, 2000));
}
}
const profile = await waitUntilReady(session.profileId!);
console.log(`Profile ${profile.id} is ${profile.status}`);import os
import sys
import time
from playwright.sync_api import sync_playwright
from steel import Steel
client = Steel()
profile_id = os.environ.get("PROFILE_ID")
if profile_id:
session = client.sessions.create(profile_id=profile_id, persist_profile=True)
else:
session = client.sessions.create(persist_profile=True)
print(f"Session {session.id}")
print(f"Watch it live at {session.session_viewer_url}")
try:
if sys.stdin.isatty():
input("Open the URL, then press Enter.")
with sync_playwright() as playwright:
browser = playwright.chromium.connect_over_cdp(session.websocket_url)
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
secure = "https://steel.dev/practice/secure"
page.goto(secure)
if page.url == secure:
print("Already signed in")
else:
page.get_by_label("Username").fill("tomsmith")
page.get_by_label("Password").fill("SuperSecretPassword!")
page.get_by_role("button", name="Login").click()
page.wait_for_url(secure)
print("Signed in")
print(page.locator("h4").inner_text())
browser.close()
finally:
released = client.sessions.release(session.id)
print(released.message)
def wait_until_ready(profile_id):
deadline = time.monotonic() + 60
while True:
profile = client.profiles.get(profile_id)
if profile.status == "READY":
return profile
if profile.status == "FAILED":
raise RuntimeError(f"Steel could not save profile {profile_id}.")
if time.monotonic() > deadline:
raise RuntimeError(f"Profile {profile_id} is not ready after 60 seconds.")
time.sleep(2)
profile = wait_until_ready(session.profile_id)
print(f"Profile {profile.id} is {profile.status}")Steel saves a new profile after the release. Until the save is done, the profile is UPLOADING, and a session cannot start from it. That is why the program waits for READY. It checks every 2 seconds, and it stops with an error if the save fails, or if the profile is not ready after 60 seconds.
Run the program. The first run signs in, and Steel saves the browser to a new profile:
Session 819b3137-d052-40e3-ae0b-7c5d6ed600ec
Watch it live at https://app.steel.dev/sessions/819b3137-d052-40e3-ae0b-7c5d6ed600ec
Open the URL, then press Enter.
Signed in
Welcome to the Secure Area. When you are done click logout below.
Session released successfully.
Profile 55f0422d-5ea1-4997-b4b8-3c578b799068 is READYPut the ID that your run printed in PROFILE_ID, and run the program again:
export PROFILE_ID=55f0422d-5ea1-4997-b4b8-3c578b799068
npx tsx automation.mtsexport PROFILE_ID=55f0422d-5ea1-4997-b4b8-3c578b799068
python automation.pyThe second run starts from the profile. Its browser has the cookies from the first run, so the site opens the secure area at once, and the program does not sign in:
Session 68235dbc-20f5-4359-8e8c-3d59996d9d08
Watch it live at https://app.steel.dev/sessions/68235dbc-20f5-4359-8e8c-3d59996d9d08
Open the URL, then press Enter.
Already signed in
Welcome to the Secure Area. When you are done click logout below.
Session released successfully.
Profile 55f0422d-5ea1-4997-b4b8-3c578b799068 is READYIf the second run prints Signed in and a new profile ID, PROFILE_ID is not set in the terminal where you ran the program.
The second run saves to the profile too, so the profile keeps what changes in each run, such as a cookie that the site renews. The profile stays READY while Steel saves the changes. Update a profile explains this. A site can still end a sign-in, for example after some days. Then the program signs in again, and the profile keeps the new sign-in.
4. Review the run
A session's details and its recording stay after the session ends. Read them to check what a run did, for example when a run fails while no one watches.
Save this program as review.mts or review.py. It reads a session's ID from the SESSION_ID environment variable:
import Steel from "steel-sdk";
const client = new Steel();
const session = await client.sessions.retrieve(process.env.SESSION_ID!);
console.log(`Status: ${session.status}`);
console.log(`Release reason: ${session.releaseReason}`);
console.log(`Duration: ${session.duration} ms`);
console.log(`Signals: ${session.signals.join(", ")}`);
const cost = await client.sessions.cost(session.id);
console.log(`Cost: ${cost.totalCost.toFixed(6)} USD`);
console.log(`Replay it at ${session.sessionViewerUrl}`);import os
from steel import Steel
client = Steel()
session = client.sessions.retrieve(os.environ["SESSION_ID"])
print(f"Status: {session.status}")
print(f"Release reason: {session.release_reason}")
print(f"Duration: {session.duration} ms")
print(f"Signals: {', '.join(session.signals)}")
cost = client.sessions.cost(session.id)
print(f"Cost: {cost.total_cost:.6f} USD")
print(f"Replay it at {session.session_viewer_url}")The program prints:
statusandreleaseReason: whether the session ended, and why. Session lifecycle lists the reasons.duration: how long the session ran, in milliseconds.signals: labels that Steel adds to a session after it ends. Signals explains them.- The session's cost in US dollars, from
sessions.cost. Session cost shows the usage behind it. - The session viewer's URL, which now plays the session's recording.
Run it with the ID of the second run from step 3:
SESSION_ID=68235dbc-20f5-4359-8e8c-3d59996d9d08 npx tsx review.mtsSESSION_ID=68235dbc-20f5-4359-8e8c-3d59996d9d08 python review.pyStatus: released
Release reason: user_requested
Duration: 6572 ms
Signals: context_restored
Cost: 0.000194 USD
Replay it at https://app.steel.dev/sessions/68235dbc-20f5-4359-8e8c-3d59996d9d08user_requested means that your program released the session. The signal context_restored shows that the session started from the profile.
Open the URL after Replay it at. The viewer plays the recording of the run, in which the browser opens the secure area without a sign-in. Recordings explains the viewer, and how to fetch a recording with the API.
The programs released every session that they created, so nothing runs now. The profile stays in your project. Profiles says how long Steel keeps it.
Troubleshooting
The sign-in did not work
page.waitForURL: Timeout 30000ms exceeded.
=========================== logs ===========================
waiting for navigation to "https://steel.dev/practice/secure" until "load"
============================================================playwright._impl._errors.TimeoutError: Page.wait_for_url: Timeout 30000ms exceeded.
=========================== logs ===========================
waiting for navigation to "https://steel.dev/practice/secure" until "load"
============================================================Cause: The browser did not reach the secure area within 30 seconds of the click on Login. The site did not accept the username or the password, or it did not answer.
Fix: Compare the username and the password in the code with the site's sign-in page. Then run the review program of step 4 with the session's ID, and open the replay to see the page after the click. The finally block released the session, so it does not keep running.
Verify: The program prints Welcome to the Secure Area. When you are done click logout below.
Next steps
- Stay signed in across sessionsHandle a sign-in that expires in production code, and keep the password out of your code with credentials.
- Hand control to a humanLet a person finish a sign-in step that code cannot do, such as a code from a phone.
- Debug a failed sessionFind out why a run failed from its release reason, signals, logs and recording.
- Connect Playwright to SteelRun more of your own Playwright code in Steel sessions.
- IntegrationsUse Steel from an agent framework, such as Browser Use, Stagehand or the OpenAI Agents SDK.
- CommandsLet a model read the page as text and act on it one step at a time, without Playwright.
- ExamplesStart from a runnable project in the Steel cookbook.