Skip to content

Set the device and viewport

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 →

The device options set a session's window size, make the browser look like a phone, hide the window, or remove the browser's toolbars. Without them, a session is a desktop browser with a visible window of 1920 by 1080 pixels. Set them when you create the session. You cannot change them on a live session.

Which options you need depends on what reads the page. A computer-use model that clicks by coordinates needs the window size that it expects. An agent that reads a site's mobile version needs a mobile device.

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.

Set the viewport

Pass dimensions with a width and a height in pixels. The largest window is 1920 by 1080. Steel reduces a larger value to that size. The session reserves room for the browser's toolbars, as a desktop browser does, so the page sees a viewport a little smaller than dimensions: 8 pixels narrower and 91 pixels shorter. For a viewport of 1280 by 720, pass 1288 by 811. At the largest size, the window is 1919 by 1079, so a session of 1920 by 1080 gives the page a viewport of 1911 by 988. In a headless session, the viewport is as wide as dimensions and 87 pixels shorter.

This program creates a session with a window of 1280 by 800, connects Playwright, prints the size of the page's viewport, and releases the session.

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

const client = new Steel();
const session = await client.sessions.create({
  dimensions: { width: 1280, height: 800 },
});

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  const [width, height] = await page.evaluate(() => [window.innerWidth, window.innerHeight]);
  console.log(width, height);
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

Run the program:

npx tsx dimensions.mts

The viewport is 8 pixels narrower and 91 pixels shorter than dimensions:

1272 709

Emulate a mobile device

Set deviceConfig.device to "mobile". The browser then presents itself as a phone: a mobile user agent, a mobile viewport, touch input, and a mobile fingerprint that matches them. Many sites serve a simpler mobile version, with fewer menus and a smaller page, which an agent can find easier to use.

const session = await client.sessions.create({
  deviceConfig: { device: "mobile" },
});

Without dimensions, a mobile session is 508 by 1074 pixels. That is also the smallest size for a mobile session. A smaller dimensions fails with 400, and no session is created:

Mobile sessions require dimensions of at least 508x1074, but received 390x844. Increase 'dimensions' to meet the minimum, or omit them to use the mobile defaults.

The device sets the browser's fingerprint, not the session's location. To choose a country, use a proxy.

To look like a phone, use deviceConfig instead of a mobile user agent, which changes only that string and turns off Steel's fingerprint.

Run headless

A headless session runs the browser without a visible window. It shows the older live view, made from screen captures of the page, and it records page events instead of a video. Use it when your app needs those, for example to replay the events with rrweb-player, as Fetch the recording shows. Sessions are headful by default. A headful session streams the live view as video and records a video.

Set headless to true when you create the session:

const session = await client.sessions.create({ headless: true });

Run fullscreen

Set fullscreen to true to launch the browser over the whole screen, with no address bar, no tabs and no toolbars. The page gets all 1920 by 1080 pixels, and screenshots and recordings show only the page.

const session = await client.sessions.create({ fullscreen: true });

A fullscreen session is always 1920 by 1080, and it ignores dimensions. Use dimensions for a given size, or fullscreen for the whole screen, not both.

Click coordinates that you saved from a session without fullscreen do not match a fullscreen session, because the viewport changes from 1911 by 988 to 1920 by 1080. The live view's fullscreen button is different: it enlarges the view on your screen and does not change the browser.

Check that it worked

Read the viewport in the page, as the program in Set the viewport does. A window of 1280 by 800 gives 1272 709, and a fullscreen session gives 1920 1080. In a mobile session, read navigator.userAgent in the page as well. It is a phone's user agent, with Mobile in it.

Next steps