Computer

Control a graphical desktop inside a running sandbox.

Use these endpoints for browser automation, GUI testing, desktop apps, and computer-use agents that need screenshots, mouse input, keyboard input, clipboard access, window management, or live noVNC screens.

Get your API key from https://createos.sh/app/profile. Pass it as X-Api-Key: <token> on every request.

Base URL: https://api.sb.createos.sh

At a glance

Base URL: https://api.sb.createos.sh
Auth: X-Api-Key: <token> header. Get a token
Response envelope: JSON responses use JSend, {"status": "...", "data": ...}
Image response: Screenshot responses return raw image/png
Recommended shape: s-2vcpu-4gb
Required rootfs: desktop:1
Live screen requirement: ingress_enabled: true

Computer endpoints work only on sandboxes created with the desktop:1 rootfs. Non-desktop sandboxes return a conflict or unavailable-desktop error. For live noVNC screen URLs, create the sandbox with ingress_enabled: true; screenshot, mouse, keyboard, clipboard, and window operations do not require public ingress.

Terminology

Term	Meaning
Desktop	The graphical Linux session running inside the sandbox. It is separate from shell command execution.
Screen	A virtual display inside the desktop session. The primary screen is `screen-0`; additional screens can be created up to `screen-7`.
`screen_id`	The API identifier for a screen, such as `screen-0`. Use it to choose which virtual display receives screenshots, mouse input, keyboard input, clipboard reads, or window operations.
Screenshot	A PNG capture of the selected screen, a selected window, or a rectangular region. Screenshot responses are raw `image/png`, not JSON.
Cursor	The mouse pointer position on the selected screen, returned as `{ "x": ..., "y": ... }`.
Window	A visible desktop application window, such as a browser window. Windows have numeric `window_id` values returned by the window list endpoint.
`window_id`	The API identifier for a window. Use it to focus, close, move, resize, maximize, minimize, restore, inspect, or capture a specific window.
Clipboard	The desktop clipboard text for the selected screen/session. Use it to read copied text or set text that can be pasted into GUI apps.
noVNC	A browser-based live desktop view. The connect endpoint returns a short-lived URL and bearer token for one screen.
Ingress	Public HTTPS routing for the sandbox. It must be enabled when you want a noVNC URL; it is not required for direct API actions like screenshot or click.

When to use the Computer API

Use the Computer API when your workload needs to see and control a real graphical desktop instead of only running shell commands.

Good fits:

Use case	Why use it
Browser automation with visual feedback	Capture screenshots, click page elements, type text, and inspect windows.
Computer-use agents	Give an agent a screenshot/action loop over a sandboxed desktop.
GUI application testing	Launch desktop apps, drive keyboard and mouse input, and verify rendered state.
Human handoff/debugging	Create a noVNC URL so a person can view or control the desktop session.

For terminal commands, background jobs, or file transfer, use Execution & Files or Managed Processes instead.

Create a desktop sandbox

Use desktop:1 and the s-2vcpu-4gb shape for computer-use workloads. Enable ingress if you need GET /computer/screens/{screen_id}/connect to return a public noVNC URL.

Bash
1curl -X POST https://api.sb.createos.sh/v1/sandboxes \
2  -H "X-Api-Key: $CREATEOS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "shape": "s-2vcpu-4gb",
6    "rootfs": "desktop:1",
7    "ingress_enabled": true
8  }'

`desktop:1` rootfs

desktop:1 is the prebuilt graphical rootfs for the Computer API. It includes a lightweight Linux desktop, browser, virtual display stack, and command-line desktop control tools.

Included desktop stack:

Component	Used for
Ubuntu 24.04	Base operating system.
XFCE and XFCE Terminal	Desktop session and terminal UI.
Xvfb	Virtual X11 screens for headless graphical sessions.
Google Chrome	Default browser for browser automation and visual workflows.
`xdotool`	Mouse movement, clicks, keyboard typing, key press/release, cursor position, and window lookup.
`wmctrl`	Window maximize and restore actions.
`scrot`	Screenshot capture.
`xclip`	Clipboard read and write.
`x11vnc`	VNC server for each virtual screen.
noVNC and `websockify`	Browser-based live desktop access.
`xdg-open`	Open URLs and desktop targets through the default browser/application.

The rootfs also includes common fonts, icon themes, networking tools, SSH server support, DBus/X11 helpers, and a dedicated unprivileged desktop user for browser and desktop processes.

Common parameters

The endpoint sections below include request and response examples. This table is the complete parameter matrix for the Computer API, checked against the OpenAPI schema and the agent's request validation code.

All JSON request bodies reject unknown fields. Coordinates use screen pixels and must be between 0 and 65535 unless a narrower range is listed.

Endpoint	Path parameters	Query parameters	JSON body parameters
`GET /v1/sandboxes/{id}/computer/screenshot`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`; `window_id` string, optional, numeric; `x` integer, optional, minimum `0`; `y` integer, optional, minimum `0`; `width` integer, optional, `1`-`3840`; `height` integer, optional, `1`-`2160`	None
`GET /v1/sandboxes/{id}/computer/screen`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	None
`GET /v1/sandboxes/{id}/computer/cursor`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	None
`POST /v1/sandboxes/{id}/computer/mouse/move`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`x` integer, required; `y` integer, required
`POST /v1/sandboxes/{id}/computer/mouse/click`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`button` string, optional, `left`/`middle`/`right`, default `left`; `x` integer, optional; `y` integer, optional; `count` integer, optional, `1`-`10`, default `1`. `x` and `y` must be supplied together.
`POST /v1/sandboxes/{id}/computer/mouse/scroll`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`direction` string, optional, `up`/`down`, default `down`; `amount` integer, optional, `1`-`100`, default `1`
`POST /v1/sandboxes/{id}/computer/mouse/drag`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`from` object, required, with required `x` and `y`; `to` object, required, with required `x` and `y`
`POST /v1/sandboxes/{id}/computer/mouse/down`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`button` string, optional, `left`/`middle`/`right`, default `left`
`POST /v1/sandboxes/{id}/computer/mouse/up`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`button` string, optional, `left`/`middle`/`right`, default `left`
`POST /v1/sandboxes/{id}/computer/keyboard/type`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`text` string, required, maximum `65536` bytes; `delay_in_ms` integer, optional, `0`-`1000`, default `25`
`POST /v1/sandboxes/{id}/computer/keyboard/press`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`keys` array of strings, required, `1`-`16` items; each key is `1`-`64` chars and may contain letters, numbers, `_`, or `-`
`POST /v1/sandboxes/{id}/computer/keyboard/down`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`keys` array of strings, required, `1`-`16` items; each key is `1`-`64` chars and may contain letters, numbers, `_`, or `-`
`POST /v1/sandboxes/{id}/computer/keyboard/up`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`keys` array of strings, required, `1`-`16` items; each key is `1`-`64` chars and may contain letters, numbers, `_`, or `-`
`GET /v1/sandboxes/{id}/computer/clipboard`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	None
`PUT /v1/sandboxes/{id}/computer/clipboard`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`text` string, required, maximum `1048576` bytes
`POST /v1/sandboxes/{id}/computer/open`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`target` string, required, maximum `4096` bytes
`POST /v1/sandboxes/{id}/computer/launch`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`application` string, required, maximum `256` bytes; `uri` string, optional, maximum `4096` bytes
`GET /v1/sandboxes/{id}/computer/windows`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`; `application` string, optional, maximum `256` bytes	None
`GET /v1/sandboxes/{id}/computer/windows/current`	`id` string, required	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	None
`GET /v1/sandboxes/{id}/computer/windows/{window_id}`	`id` string, required; `window_id` string, required, numeric	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	None
`DELETE /v1/sandboxes/{id}/computer/windows/{window_id}`	`id` string, required; `window_id` string, required, numeric	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	None
`POST /v1/sandboxes/{id}/computer/windows/{window_id}/focus`	`id` string, required; `window_id` string, required, numeric	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	None
`GET /v1/sandboxes/{id}/computer/windows/{window_id}/geometry`	`id` string, required; `window_id` string, required, numeric	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	None
`POST /v1/sandboxes/{id}/computer/windows/{window_id}/move`	`id` string, required; `window_id` string, required, numeric	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`x` integer, required, `0`-`65535`; `y` integer, required, `0`-`65535`
`POST /v1/sandboxes/{id}/computer/windows/{window_id}/resize`	`id` string, required; `window_id` string, required, numeric	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	`width` integer, required, `1`-`3840`; `height` integer, required, `1`-`2160`
`POST /v1/sandboxes/{id}/computer/windows/{window_id}/maximize`	`id` string, required; `window_id` string, required, numeric	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	None
`POST /v1/sandboxes/{id}/computer/windows/{window_id}/minimize`	`id` string, required; `window_id` string, required, numeric	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	None
`POST /v1/sandboxes/{id}/computer/windows/{window_id}/restore`	`id` string, required; `window_id` string, required, numeric	`screen_id` string, optional, `screen-0` through `screen-7`, default `screen-0`	None
`GET /v1/sandboxes/{id}/computer/screens`	`id` string, required	None	None
`POST /v1/sandboxes/{id}/computer/screens`	`id` string, required	None	`width` integer, optional, `320`-`3840`, default `1280`; `height` integer, optional, `240`-`2160`, default `800`
`GET /v1/sandboxes/{id}/computer/screens/{screen_id}`	`id` string, required; `screen_id` string, required, `screen-0` through `screen-7`	None	None
`GET /v1/sandboxes/{id}/computer/screens/{screen_id}/connect`	`id` string, required; `screen_id` string, required, `screen-0` through `screen-7`	None	None
`POST /v1/sandboxes/{id}/computer/screens/{screen_id}/resize`	`id` string, required; `screen_id` string, required, `screen-0` through `screen-7`	None	`width` integer, required, `320`-`3840`; `height` integer, required, `240`-`2160`
`DELETE /v1/sandboxes/{id}/computer/screens/{screen_id}`	`id` string, required; `screen_id` string, required, `screen-0` through `screen-7`	None	None

For screenshot capture, window_id is mutually exclusive with the rectangular region fields. Region fields x, y, width, and height must be supplied together.

GET `/v1/sandboxes/{id}/computer/screenshot`

Capture a screen, a window, or a rectangular region as PNG.

Auth required: Yes

Request body: None.

Query parameters

Parameter	Type	Required	Description
`screen_id`	string	No	Screen to capture.
`window_id`	string	No	Window id to capture. Mutually exclusive with region fields.
`x`	integer	No	Region left coordinate. Must be supplied with `y`, `width`, and `height`.
`y`	integer	No	Region top coordinate.
`width`	integer	No	Region width.
`height`	integer	No	Region height.

Bash
1curl -o screen.png \
2  "https://api.sb.createos.sh/v1/sandboxes/sb-01K.../computer/screenshot?screen_id=screen-0" \
3  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

The response body is raw PNG bytes with Content-Type: image/png.

Notable errors: 400 invalid capture target, 404 sandbox or screen not found, 409 desktop unavailable, 429 screenshot capacity busy.

GET `/v1/sandboxes/{id}/computer/screen`

Get screen dimensions.

Auth required: Yes

Request body: None.

Example

Bash
1curl "https://api.sb.createos.sh/v1/sandboxes/sb-01K.../computer/screen" \
2  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "width": 1280,
5    "height": 800
6  }
7}

Notable errors: 404 sandbox or screen not found, 409 desktop unavailable.

GET `/v1/sandboxes/{id}/computer/cursor`

Get cursor coordinates on the selected screen.

Auth required: Yes

Request body: None.

Example

Bash
1curl "https://api.sb.createos.sh/v1/sandboxes/sb-01K.../computer/cursor" \
2  -H "X-Api-Key: $CREATEOS_API_KEY"

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "x": 420,
5    "y": 260
6  }
7}

Notable errors: 404 sandbox or screen not found, 409 desktop unavailable.

Mouse

POST `/v1/sandboxes/{id}/computer/mouse/move`

Move the cursor.

Auth required: Yes

Request body

Field	Type	Required	Description
`x`	integer	Yes	Target x coordinate.
`y`	integer	Yes	Target y coordinate.

Example

Bash
1curl -X POST https://api.sb.createos.sh/v1/sandboxes/sb-01K.../computer/mouse/move \
2  -H "X-Api-Key: $CREATEOS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"x": 420, "y": 260}'

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/mouse/click`

Click a mouse button, optionally at coordinates.

Auth required: Yes

Request body

Field	Type	Required	Description
`button`	string	No	`left`, `middle`, or `right`. Default: `left`.
`x`	integer	No	Optional click x coordinate. If supplied, `y` is required.
`y`	integer	No	Optional click y coordinate. If supplied, `x` is required.
`count`	integer	No	Number of clicks. Default: `1`, maximum: `10`.

Example

Bash
1curl -X POST https://api.sb.createos.sh/v1/sandboxes/sb-01K.../computer/mouse/click \
2  -H "X-Api-Key: $CREATEOS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"button": "left", "x": 420, "y": 260, "count": 2}'

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/mouse/scroll`

Scroll vertically.

Auth required: Yes

Request body

Field	Type	Required	Description
`direction`	string	No	`up` or `down`. Default: `down`.
`amount`	integer	No	Scroll steps. Default: `1`, maximum: `100`.

Example

Bash
1curl -X POST https://api.sb.createos.sh/v1/sandboxes/sb-01K.../computer/mouse/scroll \
2  -H "X-Api-Key: $CREATEOS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"direction": "down", "amount": 5}'

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/mouse/drag`

Drag from one coordinate to another.

Auth required: Yes

Request body

JSON
1{
2  "from": { "x": 120, "y": 220 },
3  "to": { "x": 620, "y": 220 }
4}

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/mouse/down`

Hold a mouse button down.

Auth required: Yes

Request body

JSON
1{ "button": "left" }

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/mouse/up`

Release a mouse button.

Auth required: Yes

Request body

JSON
1{ "button": "left" }

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

Notable errors: 400 invalid request body, 404 sandbox or screen not found.

Keyboard

POST `/v1/sandboxes/{id}/computer/keyboard/type`

Type text into the focused window.

Auth required: Yes

Request body

Field	Type	Required	Description
`text`	string	Yes	Text to type. Maximum 64 KiB.
`delay_in_ms`	integer	No	Delay between key events. Default: `25`, maximum: `1000`.

Example

Bash
1curl -X POST https://api.sb.createos.sh/v1/sandboxes/sb-01K.../computer/keyboard/type \
2  -H "X-Api-Key: $CREATEOS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"text": "hello from CreateOS"}'

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/keyboard/press`

Press a key or key combination.

Auth required: Yes

Request body

JSON
1{ "keys": ["Control_L", "C"] }

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/keyboard/down`

Hold one or more keys down.

Auth required: Yes

Request body

JSON
1{ "keys": ["Shift_L"] }

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/keyboard/up`

Release one or more held keys.

Auth required: Yes

Request body

JSON
1{ "keys": ["Shift_L"] }

keys must contain 1-16 key names. Key names may contain letters, numbers, _, or -.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

Notable errors: 400 invalid text or keys, 404 sandbox or screen not found.

Clipboard

GET `/v1/sandboxes/{id}/computer/clipboard`

Read desktop clipboard text.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "text": "copied text"
5  }
6}

PUT `/v1/sandboxes/{id}/computer/clipboard`

Replace desktop clipboard text.

Auth required: Yes

Request body

Field	Type	Required	Description
`text`	string	Yes	Clipboard text. Maximum 1 MiB.

Example

Bash
1curl -X PUT https://api.sb.createos.sh/v1/sandboxes/sb-01K.../computer/clipboard \
2  -H "X-Api-Key: $CREATEOS_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"text": "copied text"}'

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

Notable errors: 400 invalid clipboard text, 404 sandbox or screen not found, 409 desktop clipboard unavailable.

Open and Launch

POST `/v1/sandboxes/{id}/computer/open`

Open a URL or desktop target.

Auth required: Yes

Request body

JSON
1{ "target": "https://example.com" }

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/launch`

Launch an installed desktop application.

Auth required: Yes

Example

Bash
1curl -X POST \
2  "https://api.sb.createos.sh/v1/sandboxes/sb-01K.../computer/launch?screen_id=screen-1" \
3  -H "X-Api-Key: $CREATEOS_API_KEY" \
4  -H "Content-Type: application/json" \
5  -d '{"application": "google-chrome"}'

Request body

JSON
1{
2  "application": "google-chrome"
3}

uri is optional. Use screen_id in the query string to choose the screen where the application opens.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

Notable errors: 400 invalid target or application, 404 sandbox or screen not found.

Windows

GET `/v1/sandboxes/{id}/computer/windows`

List visible desktop windows. Add ?application=<name> to filter by application class.

Auth required: Yes

Request body: None.

Query parameters

Parameter	Type	Required	Description
`application`	string	No	Application class filter.

Success response 200

JSON
1{
2  "status": "success",
3  "data": [
4    {
5      "id": "4194307"
6    }
7  ]
8}

GET `/v1/sandboxes/{id}/computer/windows/current`

Get the focused window.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "id": "4194307"
5  }
6}

GET `/v1/sandboxes/{id}/computer/windows/{window_id}`

Get a window title.

Auth required: Yes

Request body: None.

Path parameters

Parameter	Description
`window_id`	Numeric window id.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "id": "4194307",
5    "title": "Example - Google Chrome"
6  }
7}

DELETE `/v1/sandboxes/{id}/computer/windows/{window_id}`

Request that a window close.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/windows/{window_id}/focus`

Focus a window.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

GET `/v1/sandboxes/{id}/computer/windows/{window_id}/geometry`

Get window position and dimensions.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "id": "4194307",
5    "x": 0,
6    "y": 0,
7    "width": 1280,
8    "height": 800,
9    "screen": 0
10  }
11}

POST `/v1/sandboxes/{id}/computer/windows/{window_id}/move`

Move a window.

Auth required: Yes

Request body

JSON
1{ "x": 100, "y": 80 }

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/windows/{window_id}/resize`

Resize a window.

Auth required: Yes

Request body

JSON
1{ "width": 1000, "height": 700 }

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/windows/{window_id}/maximize`

Maximize a window.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/windows/{window_id}/minimize`

Minimize a window.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

POST `/v1/sandboxes/{id}/computer/windows/{window_id}/restore`

Restore a maximized window.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

Notable errors: 400 invalid window id or dimensions, 404 sandbox, screen, or window not found.

Screens and noVNC

GET `/v1/sandboxes/{id}/computer/screens`

List configured desktop screens.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": [
4    {
5      "screen_id": "screen-0",
6      "display": ":0",
7      "width": 1280,
8      "height": 800,
9      "vnc_port": 5900,
10      "novnc_port": 6080
11    }
12  ]
13}

POST `/v1/sandboxes/{id}/computer/screens`

Create an additional screen. The sandbox supports at most eight screens, including screen-0.

Auth required: Yes

Request body

JSON
1{ "width": 1280, "height": 800 }

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "screen_id": "screen-1",
5    "display": ":1",
6    "width": 1280,
7    "height": 800,
8    "vnc_port": 5901,
9    "novnc_port": 6081
10  }
11}

GET `/v1/sandboxes/{id}/computer/screens/{screen_id}`

Get one configured screen.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "screen_id": "screen-0",
5    "display": ":0",
6    "width": 1280,
7    "height": 800,
8    "vnc_port": 5900,
9    "novnc_port": 6080
10  }
11}

GET `/v1/sandboxes/{id}/computer/screens/{screen_id}/connect`

Create a live noVNC connection URL. This requires sandbox ingress to be enabled.

Each call rotates the screen bearer token. Previously issued URLs cannot establish new websocket sessions. The new token expires after one hour.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "screen_id": "screen-0",
5    "port": 6080,
6    "path": "vnc.html?autoconnect=1&resize=remote&path=websockify%3Ftoken%3Dabc...",
7    "token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
8    "expires_at": "2026-08-25T12:00:00Z",
9    "url": "https://sb-01K...-6080.public-sb.example/vnc.html?autoconnect=1&resize=remote&path=websockify%3Ftoken%3Dabc..."
10  }
11}

POST `/v1/sandboxes/{id}/computer/screens/{screen_id}/resize`

Resize an existing screen. This restarts the selected display, disconnects existing noVNC sessions, and invalidates previously issued connection tokens.

Auth required: Yes

Request body

JSON
1{ "width": 1440, "height": 900 }

Success response 200

JSON
1{
2  "status": "success",
3  "data": {
4    "screen_id": "screen-0",
5    "display": ":0",
6    "width": 1440,
7    "height": 900,
8    "vnc_port": 5900,
9    "novnc_port": 6080
10  }
11}

DELETE `/v1/sandboxes/{id}/computer/screens/{screen_id}`

Delete an additional screen. screen-0 is the primary screen and cannot be deleted.

Auth required: Yes

Request body: None.

Success response 200

JSON
1{
2  "status": "success",
3  "data": {}
4}

Notable errors: 400 invalid screen id or dimensions, 404 sandbox or screen not found, 409 screen limit reached, primary screen delete, ingress disabled for connect, or desktop unavailable.

100,000+ Builders. One Platform.