Skip to content

Fingerprints

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 browser fingerprint is the set of values that a site reads to tell one browser from another, such as the user agent, platform, fonts and media devices. Steel gives each session a realistic fingerprint, so that the browser looks like a common browser and not like automation. You do not need an option for it.

You can make the input human-like with humanizeInteractions, turn the fingerprint off with skipFingerprintInjection, or send your own userAgent. How stealth works explains what sites check.

Before you begin

Put your Steel API key in the STEEL_API_KEY environment variable. Then install the Steel SDK and Playwright.

npm install steel-sdk playwright

In Go and Rust, install only the SDK, as the Go and Rust SDK pages show. The code that drives the browser uses Playwright, so it is in TypeScript and Python only.

How fingerprints are set

When a session starts, Steel picks a desktop fingerprint and injects it into the browser. These settings change that choice:

  • A session that starts from a profile uses the user agent that the profile saved, or the request's userAgent if it sets one. Steel injects no other fingerprint values into it.
  • A session with deviceConfig set to { device: "mobile" } gets a mobile fingerprint. See Set the device and viewport.
  • A session with a custom userAgent gets no fingerprint from Steel. See Set a user agent.

This program creates a session and prints two of the values that a site reads.

fingerprint.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();
const session = await client.sessions.create();

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  const values = await page.evaluate(() =>
    JSON.stringify({ userAgent: navigator.userAgent, platform: navigator.platform }),
  );
  console.log(values);
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx fingerprint.mts

The program prints both values. They can change from one session to the next.

{"userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/157.0.0.0 Safari/537.36","platform":"Linux x86_64"}

Make input human-like

Set humanizeInteractions to true in stealthConfig. Steel then moves the mouse along a curved path to each point, and adds a random pause of 10 to 150 milliseconds before each key event. It does this only for the mouse and keyboard input that your code sends over CDP (Chrome DevTools Protocol), not for Commands, computer actions, the MCP server or the CLI. Use humanizeInteractions on sites that watch how the pointer moves and how fast text appears.

const session = await client.sessions.create({
  stealthConfig: { humanizeInteractions: true },
});

Your code does not change. Steel changes the Input.dispatchMouseEvent and Input.dispatchKeyEvent commands that reach the session, whichever library sends them.

Skip fingerprint injection

Set skipFingerprintInjection to true in stealthConfig. Steel then does not generate a fingerprint for the session, and the browser shows its own values.

const session = await client.sessions.create({
  stealthConfig: { skipFingerprintInjection: true },
});

Use this option only when your code sets the fingerprint itself.

Set a user agent

Set userAgent to the string that the browser sends. Use it when a site expects a certain user agent, or when a site allows your crawler by its name.

This program creates a session with a user agent and prints the user agent that a page sees.

user-agent.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

const client = new Steel();
const session = await client.sessions.create({
  userAgent: "ExampleCrawler/1.0 (+https://example.com/crawler)",
});

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  console.log(await page.evaluate(() => navigator.userAgent));
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx user-agent.mts

The program prints the user agent that you set.

ExampleCrawler/1.0 (+https://example.com/crawler)

Check that it worked

The values that the programs print show what a page reads, not whether a site accepts the session. To check that, run your task on the site several times with the same options. When the fingerprint and humanizeInteractions work, the sessions end without the signal bot_detection_triggered, as Check the signals shows.

Next steps