Computer
Capture screens and control desktop applications inside a running sandbox. Use a desktop-capable rootfs from GET /v1/rootfs, such as desktop:1 when available. A running sandbox on a minimal image does not provide a desktop.
Base URL: https://api.sb.createos.sh. Authenticate with X-Api-Key; you must own the sandbox. All paths below start with /v1/sandboxes/{id}/computer. JSON responses use JSend, except screenshots, which return PNG bytes.
Capture and desktop state
| Method | Path | Request / result |
|---|---|---|
| GET | /screenshot | PNG screenshot. Optional query: screen_id, window_id, or a rectangle (x, y, width, height). |
| GET | /screen | Screen dimensions: { width, height }. |
| GET | /cursor | Cursor position: { x, y }. |
| GET | /clipboard | Clipboard contents: { text }. |
| PUT | /clipboard | Body: { "text": "hello" }. |
| POST | /open | Body: { "target": "https://example.com" }. |
| POST | /launch | Body: { "application": "...", "uri": "..." }; uri is optional. Application must be installed. |
For desktop operations, omit screen_id to use the primary screen. Use screen_id=screen-1, for example, to target an existing additional screen.
Bash
Mouse and keyboard
Each operation uses POST and accepts optional screen_id in the query.
| Path | JSON body |
|---|---|
/mouse/move | { "x": 100, "y": 200 } |
/mouse/click | Optional button (left, middle, right), count, and coordinates. Supply x and y together or omit both. |
/mouse/scroll | Optional direction (up, down) and amount. |
/mouse/drag | { "from": { "x": 100, "y": 200 }, "to": { "x": 300, "y": 400 } } |
/mouse/down, /mouse/up | Optional { "button": "left" }. |
/keyboard/type | { "text": "hello", "delay_in_ms": 10 }; delay is optional. |
/keyboard/press | { "keys": ["ctrl", "a"] } |
/keyboard/down, /keyboard/up | { "keys": ["shift"] } |
Windows
| Method | Path | Request / result |
|---|---|---|
| GET | /windows | Array of windows with id and optional title. Optional application filter. |
| GET | /windows/current | Current window. |
| GET | /windows/{window} | One window. |
| GET | /windows/{window}/geometry | id, x, y, width, height, screen. |
| POST | /windows/{window}/focus | Focus the window. |
| POST | /windows/{window}/move | Body: { "x": 100, "y": 200 }. |
| POST | /windows/{window}/resize | Body: { "width": 800, "height": 600 }. |
| POST | /windows/{window}/maximize | Maximize. |
| POST | /windows/{window}/minimize | Minimize. |
| POST | /windows/{window}/restore | Restore. |
| DELETE | /windows/{window} | Close. |
Window operations accept optional screen_id in the query. URL-encode the window ID.
Screens and browser connections
| Method | Path | Request / result |
|---|---|---|
| GET | /screens | Array of screen records. |
| POST | /screens | Optional width and height; defaults to 1280 × 800. Returns a new screen with HTTP 201. |
| GET | /screens/{screen} | One screen record. |
| POST | /screens/{screen}/resize | Body: { "width": 1280, "height": 800 }. |
| DELETE | /screens/{screen} | Delete an additional screen. The primary screen cannot be deleted. |
| GET | /screens/{screen}/connect | Fresh connection details for browser access. |
Screen IDs range from screen-0 to screen-7. A screen record contains screen_id, display, width, height, vnc_port, and novnc_port.
The /connect endpoint requires public ingress to be enabled on the sandbox. Enable it through the Sandbox PATCH API before requesting a connection.
Connection details contain screen_id, port, path, token, expires_at, and url when available. Treat tokens and token-bearing URLs as credentials. Use the returned URL and request fresh details after expiry. Requesting a new connection token invalidates the previous token for new connections; existing sessions stay connected.
Errors: 400 invalid input, 404 sandbox or screen not found, 409 sandbox/desktop unavailable, ingress disabled for a screen connection, or screen conflict; 429 screenshot capacity busy; 501 desktop tools unavailable; 502 service unavailable upstream. Creating a ninth screen or deleting the primary screen returns 409.
For TypeScript examples, see SDK Computer.