Skip to content

Snapshots and refs

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

A snapshot is a text version of a page that a language model can read. It lists the page's elements. Each element that you can act on or point to, such as a link, a field or a heading, gets a short name: its ref. The model reads the snapshot, picks a ref, and sends it back in a command such as click. Commands, the MCP server and the Steel CLI all work this way. Some names differ, such as press_key in the MCP server for the press command. Names in the CLI and the MCP server maps them.

A screenshot shows pixels, and a page's HTML holds far more than a model needs. A snapshot keeps what a person would use: the headings, links, fields and buttons, with their names and states.

Snapshots

A snapshot is the page's accessibility tree, as text. Each line is one element: its role, its name in quotes, its states in brackets, and its ref. A field's value follows the colon. Plain text, such as a paragraph, has no ref.

- heading "Account" [level=1, ref=e1]
- textbox "Name" [ref=e2]: Ada
- checkbox "Remember me" [checked=false, ref=e3]
- button "Save" [ref=e4]
- generic "Open card" [ref=e5] clickable [cursor:pointer]

These options make a snapshot shorter:

OptionThe snapshot keeps
interactiveOnly the lines with refs. This fits most agent steps.
compactThe lines with refs or values, and their ancestors.
depthThe lines up to this depth.

Each snapshot has a snapshotId. After an action, a request can ask for a new snapshot, or for a diff against the tab's last snapshot. A diff lists only the lines that changed, so the model reads less after each step.

A password field shows as •••••••• in a snapshot, and in the text that other commands return. A get of its value leaves the value out and sets masked to true. Any field that shows dots instead of its text is masked the same way. When Steel fills a sign-in form with a credential, it shows dots in the username field too, so a snapshot masks the username as well. When the session sets the credentials option blurFields to false, the username shows as it is.

Refs

A ref, such as e12, names one element on one page. It stays the same across snapshots of that page, so a model can act on a ref from an older snapshot while the element is still there.

A ref goes stale when its element leaves the page, or when the page reuses the element for other content, as a list can. A command on a stale ref fails with stale_ref. Take a new snapshot, and pick the element again.

A ref is valid only in its session. To find the same element in a later session, use a locator: its role and name, its label, its text, or a CSS selector. The get command with what set to locator returns locators for an element, best first. A command accepts a ref, a CSS selector or a locator as its target.

In a snapshot, a ref shows as ref=e12. Pass it to a command as e12 or as ref=e12.

A ref also knows its tab, so a command on a ref acts on that tab and needs no tab field. Tabs in the Commands reference explains how other commands pick a tab, and how to answer a JavaScript dialog that blocks one.

Page state and after

Every response with status 200 has a next value. Send it as after in your next request. It tells Steel which state of the session you last saw.

When you retry with the same after and the same commands, Steel does not run the commands again. The retry returns the stored result.

When the session has changed since that next, the response sets epochChanged to true. Another execution that changed the page, or a browser restart, counts as a change. Input from a CDP client or from the live view does not count.

When something else has changed the page, take a new snapshot before you act on old refs. If Steel no longer knows your after, the request fails with invalid_operation_token, and the response carries a fresh next. Check the page before you send the commands again, because they may have run.

Executions

Each request runs as one execution, with an ID such as x-1. Its commands run in order and stop at the first failure. Steel does not undo the commands that already ran.

Executions in the Commands reference has an execution's states, how long a response waits for it, and the rules for a safe retry.