---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/sessions/devices
markdown_url: https://steel.dev/docs/sessions/devices.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Set the device and viewport
description: Choose a desktop or a mobile browser, set the viewport size, and run headless or fullscreen with the session's device options.
summary: Choose a desktop or a mobile browser, set the viewport size, and run headless or fullscreen with the session's device options.
type: how-to
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/sessions/lifecycle.md
related:
  - https://steel.dev/docs/sessions/lifecycle.md
  - https://steel.dev/docs/sessions/timeouts.md
  - https://steel.dev/docs/sessions/metadata.md
  - https://steel.dev/docs/sessions/bandwidth.md
  - https://steel.dev/docs/sessions/files.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Set the device and viewport

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.

**TypeScript**

```sh
npm install steel-sdk playwright
```

**Python**

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwright
```

In Go and Rust, install only the SDK, as the [Go](https://steel.dev/docs/reference/sdks/go#install) and [Rust](https://steel.dev/docs/reference/sdks/rust#install) 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.

**TypeScript**

```ts file=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);
}
```

**Python**

```python file=dimensions.py
from playwright.sync_api import sync_playwright
from steel import Steel

client = Steel()
session = client.sessions.create(
    dimensions={"width": 1280, "height": 800},
)

try:
    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()
        width, height = page.evaluate("[window.innerWidth, window.innerHeight]")
        print(width, height)
        browser.close()
finally:
    client.sessions.release(session.id)
```

Run the program:

**TypeScript**

```sh
npx tsx dimensions.mts
```

**Python**

```sh
python dimensions.py
```

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

```text nocopy
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.

**TypeScript**

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

**Python**

```python
session = client.sessions.create(
    device_config={"device": "mobile"},
)
```

**Go**

```go
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	DeviceConfig: steel.F(steel.SessionNewParamsDeviceConfig{
		Device: steel.F(steel.SessionNewParamsDeviceConfigDeviceMobile),
	}),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        device_config: Some(steel_rs::SessionCreateParamsDeviceConfig {
            device: Some(steel_rs::SessionCreateParamsDeviceConfigDevice::Mobile),
        }),
        ..Default::default()
    })
    .await?;
```

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:

```text nocopy
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](https://steel.dev/docs/stealth/proxies).

To look like a phone, use `deviceConfig` instead of a mobile [user agent](https://steel.dev/docs/stealth/fingerprints#set-a-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](https://steel.dev/docs/observability/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](https://steel.dev/docs/observability/recordings#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:

**TypeScript**

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

**Python**

```python
session = client.sessions.create(headless=True)
```

**Go**

```go
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	Headless: steel.F(true),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        headless: Some(true),
        ..Default::default()
    })
    .await?;
```

## 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.

**TypeScript**

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

**Python**

```python
session = client.sessions.create(fullscreen=True)
```

**Go**

```go
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	Fullscreen: steel.F(true),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        fullscreen: Some(true),
        ..Default::default()
    })
    .await?;
```

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](https://steel.dev/docs/sessions/devices#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

- [Computer actions](https://steel.dev/docs/control/computer-actions): Click and type at coordinates in the viewport that you set.
