> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# See the screen

> Start the display, capture it, and watch it live

Start the runtime's screen, capture it, resize it, and publish a link to watch it live. Use the screen for windows, dialogs, and anything a page's elements cannot describe.

CLI and cURL examples use `$RT` for a `desktop-small` runtime ([Overview](https://docs.gravixlayer.ai/documentation/agentruntime/computer-use/overview.md#requirements)).

## Start the display

`enable` starts the display server and returns its status; calling it again
returns the running display's status unchanged, so it is safe to call first
in every script. Enable the display **before** `browser.open` to get a
headed browser window. The sections below assume the display is enabled.

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()  # reads GRAVIXLAYER_API_KEY
sandbox = client.runtime.create(template="desktop-small")

st = sandbox.desktop.enable(width=1920, height=1080)
print(st["enabled"], st["display"])  # True :0

print(sandbox.desktop.status())
print(sandbox.desktop.info())      # live geometry — follows resizes
print(sandbox.desktop.position())  # {"x": 960, "y": 540}
print(sandbox.desktop.keys())      # key names press/hotkey accept
sandbox.kill()
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // reads GRAVIXLAYER_API_KEY
const sandbox = await client.runtime.create({ template: 'desktop-small' });

const st = await sandbox.desktop.enable({ width: 1920, height: 1080 });
console.log(st.enabled, st.display); // true :0

console.log(await sandbox.desktop.status());
console.log(await sandbox.desktop.info());     // live geometry — follows resizes
console.log(await sandbox.desktop.position()); // { x: 960, y: 540 }
console.log(await sandbox.desktop.keys());     // key names press/hotkey accept
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime desktop enable "$RT" --width 1920 --height 1080
gravixlayer runtime desktop status "$RT"
gravixlayer runtime desktop info "$RT"
gravixlayer runtime desktop position "$RT"
gravixlayer runtime desktop keys "$RT"
```

```bash cURL theme={null}
API="https://api.gravixlayer.ai/v1"

curl -sS -X POST "$API/agents/runtime/$RT/display/enable" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"width":1920,"height":1080}'

curl -sS "$API/agents/runtime/$RT/display/status" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

curl -sS "$API/agents/runtime/$RT/display/info" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
```

**Enable parameters**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `width` | int | No | Framebuffer width — `1920` when omitted |
| `height` | int | No | Framebuffer height — `1080` when omitted |
| `depth` | int | No | Color depth: `8`, `15`, `16`, `24` (default), `30`, or `32` |
| `display` | string | No | Display name (default `:0`) |
| `wm` | string | No | Window manager to start (default none) |
| `mode` | string | No | `auto` (default) attaches to the session's display when the template ships one and spawns a virtual display otherwise; `spawn` forces a new virtual display; `attach` requires a session display |
| `dpi` | int | No | Logical dots-per-inch — platform default `96` when omitted; fonts and DPI-aware apps scale with it |

`resize` accepts the same `dpi` field: `0` (default) preserves the current density, a positive value re-pins it alongside the new geometry.

## Capture the screen

`screenshot` returns the frame as base64 PNG, JPEG, or WebP — crop with
`region`, shrink with `scale_pct`/`max_width`/`max_height`, or pass
`wait_stable_ms` to capture only after the screen stops changing.
`wait_stable` is the standalone version: block until the screen has been
pixel-quiet for `stable_ms`.

```python Python theme={null}
import base64
from gravixlayer import GravixLayer

client = GravixLayer()
sandbox = client.runtime.create(template="desktop-small")
sandbox.desktop.enable()

# Capture after the screen settles — the anti-flake pattern.
shot = sandbox.desktop.screenshot(wait_stable_ms=500)
with open("screen.png", "wb") as f:
    f.write(base64.b64decode(shot["data"]))

print(sandbox.desktop.wait_stable(stable_ms=300, timeout_ms=10_000))
sandbox.kill()
```

```typescript TypeScript theme={null}
import { writeFileSync } from 'node:fs';
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create({ template: 'desktop-small' });
await sandbox.desktop.enable();

// Capture after the screen settles — the anti-flake pattern.
const shot = await sandbox.desktop.screenshot({ waitStableMs: 500 });
writeFileSync('screen.png', Buffer.from(shot.data, 'base64'));

console.log(await sandbox.desktop.waitStable(300, 10_000));
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime desktop screenshot "$RT" --out screen.png --wait-stable-ms 500
gravixlayer runtime desktop wait-stable "$RT" --stable-ms 300 --timeout-ms 10000
```

```bash cURL theme={null}
API="https://api.gravixlayer.ai/v1"

curl -sS -X POST "$API/agents/runtime/$RT/display/screenshot" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"png","wait_stable_ms":500}' | jq -r .data | base64 -d > screen.png

curl -sS -X POST "$API/agents/runtime/$RT/display/wait_stable" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stable_ms":300,"timeout_ms":10000}'
```

**Screenshot parameters**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `format` | string | No | `png` (default), `jpeg`, or `webp` |
| `region` | object | No | Crop `{x, y, w, h}` in screen pixels (`width`/`height` accepted as aliases) |
| `quality` | int | No | JPEG/WebP quality 1–100 |
| `scale_pct` | int | No | Downscale percentage |
| `max_width`, `max_height` | int | No | Fit inside these bounds preserving aspect — the reply's `scale` reports the applied factor |
| `cursor` | bool | No | Composite the pointer into the shot |
| `wait_stable_ms` | int | No | Require pixel-quiet this long first |
| `timeout_ms` | int | No | Give up waiting after this (default `5000`) |
| `if_rev` | int | No | Skip encode/transfer when the frame still equals this revision — the reply then has `unchanged: true` and empty `data` |

Screenshot returns `{data, format, width, height, scale, rev, unchanged}`
with `data` base64. Feed `rev` back as `if_rev` on the next call to skip
unchanged frames; use `coordinate_space="screenshot"` on input calls to
address fitted coordinates. `wait_stable` returns `{settled, waited_ms, rev}`
(`waitedMs` in TypeScript) — `rev` is the frame revision at settle.

## Resize the display

`resize` changes the framebuffer geometry live — no disable/enable cycle.
Returns the new live geometry; `info` reports it too.

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
sandbox = client.runtime.create(template="desktop-small")
sandbox.desktop.enable(width=1920, height=1080)

print(sandbox.desktop.resize(1280, 720))
sandbox.kill()
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create({ template: 'desktop-small' });
await sandbox.desktop.enable({ width: 1920, height: 1080 });

console.log(await sandbox.desktop.resize(1280, 720));
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime desktop resize "$RT" 1280 720
```

```bash cURL theme={null}
API="https://api.gravixlayer.ai/v1"

curl -sS -X POST "$API/agents/runtime/$RT/display/resize" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"width":1280,"height":720}'
```

## Watch the screen live

`view` publishes a private watch URL for the screen. Open **`browser_url`** —
it carries a fresh auth token that signs the browser in. Every `view` call
mints a new token, so repeat calls always return a working link; each mint
invalidates the previous token (viewers already connected keep their live
session). `rotate_token`/`rotateToken`/`--rotate-token` is accepted but no
longer needed. URLs expire after an hour. `stop_view`
tears the view server down and frees its port.

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
sandbox = client.runtime.create(template="desktop-small")
sandbox.desktop.enable()

v = sandbox.desktop.view(fps=10)
print(v["browser_url"])  # open this to watch live
# The URL stops working when the runtime is killed — or on stop_view().
sandbox.desktop.stop_view()
sandbox.kill()
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create({ template: 'desktop-small' });
await sandbox.desktop.enable();

const v = await sandbox.desktop.view({ fps: 10 });
console.log(v.browserUrl); // open this to watch live
// The URL stops working when the runtime is killed — or on stopView().
await sandbox.desktop.stopView();
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime desktop view "$RT" --fps 10   # prints browser_url
gravixlayer runtime desktop stop-view "$RT"
```

```bash cURL theme={null}
API="https://api.gravixlayer.ai/v1"

curl -sS -X POST "$API/agents/runtime/$RT/display/view" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fps":10,"quality":80}' | jq -r .browser_url

curl -sS -X POST "$API/agents/runtime/$RT/display/view/stop" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
```

`fps` defaults to 15 and caps at 30; `quality` is JPEG quality 1–100.
`window_id` streams only that window's pixels. The call returns `201` with
the web-service record — `browser_url`, `url`, `port`, `expires_at`, and
`token` (fresh on every call). See
[Web Services](https://docs.gravixlayer.ai/documentation/agentruntime/getting-started/web-services.md) for how
private URLs authenticate.

**Watch-only links.** `role="watch"` (`role: 'watch'`, `--role watch`)
mints a view-only `view_token` — a connection holding it sees frames but
can never inject input. The SDKs compose it into `watch_url`/`watchUrl`
(`browser_url` + `&vt=<view_token>`); cURL appends `&vt=` itself. Hand the
watch URL to a human observer and keep the control URL for the agent. The
view server enforces `vt=` on the websocket upgrade — a missing or bad
token is refused.

## Stop the display

`disable` stops the display server; headed browser windows go with it.
`enable` starts it again.

```python Python theme={null}
from gravixlayer import GravixLayer

client = GravixLayer()
sandbox = client.runtime.create(template="desktop-small")
sandbox.desktop.enable()

sandbox.desktop.disable()
print(sandbox.desktop.status()["enabled"])  # False
sandbox.kill()
```

```typescript TypeScript theme={null}
import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer();
const sandbox = await client.runtime.create({ template: 'desktop-small' });
await sandbox.desktop.enable();

await sandbox.desktop.disable();
console.log((await sandbox.desktop.status()).enabled); // false
await sandbox.kill();
```

```bash CLI theme={null}
gravixlayer runtime desktop disable "$RT"
```

```bash cURL theme={null}
API="https://api.gravixlayer.ai/v1"

curl -sS -X POST "$API/agents/runtime/$RT/display/disable" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
```

## Click the right pixel

* Display coordinates are absolute screen pixels. `region` uses the same
  space, so a point in a cropped screenshot maps back by adding the region's
  `x` and `y`; for scaled or fitted shots, `coordinate_space="screenshot"`
  on input calls does the mapping for you.
* `wait_stable` beats a fixed sleep: it returns as soon as the screen stops
  moving instead of waiting out the worst case.
* Prefer browser actions over desktop input for web work — refs survive
  layout shifts where coordinates do not. Reach for the desktop when the
  target is outside the DOM.

## Endpoints

| Method | Path | Description |
| - | - | - |
| POST | `/v1/agents/runtime/{runtime_id}/display/enable` | Start the display server |
| POST | `/v1/agents/runtime/{runtime_id}/display/disable` | Stop it |
| GET | `/v1/agents/runtime/{runtime_id}/display/status` | Enable-time config and state |
| GET | `/v1/agents/runtime/{runtime_id}/display/info` | Live geometry (follows resizes) |
| GET | `/v1/agents/runtime/{runtime_id}/display/position` | Live pointer coordinates |
| GET | `/v1/agents/runtime/{runtime_id}/display/keys` | Key names `press`/`hotkey` accept |
| POST | `/v1/agents/runtime/{runtime_id}/display/screenshot` | Capture the screen (base64) |
| POST | `/v1/agents/runtime/{runtime_id}/display/wait_stable` | Block until pixels stop changing |
| POST | `/v1/agents/runtime/{runtime_id}/display/resize` | Live-resize the framebuffer |
| POST | `/v1/agents/runtime/{runtime_id}/display/view` | Mint a live-watch URL |
| POST | `/v1/agents/runtime/{runtime_id}/display/view/control` | Set takeover mode (`shared\|human\|agent`) |
| POST | `/v1/agents/runtime/{runtime_id}/display/view/stop` | Stop the view server |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.