Computer

Use sandbox.computer to capture screenshots and control a desktop. Choose a desktop-capable image such as desktop:1 when it appears in client.listRootfs(). The sandbox must be running with its desktop available. Minimal images do not include the required desktop tools. Use an SDK version that exports SandboxComputer.

Capture and interact

import { createClient } from "@nodeops-createos/sandbox";
 
const client = createClient();
const sandbox = await client.createSandbox({
  shape: "s-4vcpu-4gb",
  rootfs: "desktop:1",
});
try {
  await sandbox.waitUntilRunning();
  const dimensions = await sandbox.computer.screen();
  console.log(dimensions.width, dimensions.height);
  await sandbox.computer.open("https://example.com");
  const png = await sandbox.computer.screenshot();
  console.log("PNG bytes:", png.byteLength);
} finally {
  await sandbox.destroy();
}

Desktop applications can take time to open. Check the screen or window state before sending input that depends on an application being ready.

Screen selection and request options

Most desktop methods accept ComputerScreenOptions as their final argument: { screenId?, ...requestOptions }. Omit screenId for the primary screen. Screen IDs run from screen-0 to screen-7. The screens methods take a screen ID as a positional argument where needed and accept ordinary RequestOptions.

Desktop methods

Method	Result
`screenshot(options?)`	PNG bytes as `Promise<ArrayBuffer>`. Options add `windowId` or a rectangle (`x`, `y`, `width`, `height`).
`screen(options?)`	`{ width, height }`.
`cursor(options?)`	`{ x, y }`.
`clipboard(options?)`	`{ text }`.
`setClipboard(textOrObject, options?)`	Replace clipboard text using a string or `{ text }`.
`open(targetOrObject, options?)`	Open a URL or desktop target using a string or `{ target }`.
`launch({ application, uri? }, options?)`	Launch an installed application.

Mutation methods return Promise<OKResponse> unless a result is listed. Reading a screenshot returns binary data; other methods unwrap the JSON response.

Mouse and keyboard

Method	Request
`mouse.move({ x, y }, options?)`	Cursor coordinates.
`mouse.click(request?, options?)`	Optional `button` (`left`, `middle`, `right`), `count`, and paired `x`/`y` coordinates.
`mouse.scroll(request?, options?)`	Optional `direction` (`up`, `down`) and `amount`.
`mouse.drag({ from, to }, options?)`	Each endpoint is `{ x, y }`.
`mouse.down(request?, options?)` / `mouse.up(request?, options?)`	Optional `{ button }`.
`keyboard.type(textOrObject, options?)`	String or `{ text, delay_in_ms? }`.
`keyboard.press(keysOrObject, options?)`	Key array such as `["ctrl", "a"]`, or `{ keys: [...] }`.
`keyboard.down(keysOrObject, options?)` / `keyboard.up(keysOrObject, options?)`	Hold or release keys.

These methods return Promise<OKResponse>.

Windows

Use computer.windows.list({ application?, screenId? }) to obtain window IDs. current(options?) and get(windowId, options?) return a window with id and optional title. geometry(windowId, options?) returns id, x, y, width, height, and screen.

Use focus(windowId), move(windowId, { x, y }), resize(windowId, { width, height }), maximize(windowId), minimize(windowId), restore(windowId), or close(windowId) to control a window. Each accepts screen/request options as its final argument and returns Promise<OKResponse>.

Additional screens and browser access

Method	Result
`screens.list(options?)`	`ComputerScreen[]`.
`screens.create({ width?, height? }?, options?)`	New `ComputerScreen`. Default dimensions: 1280 × 800.
`screens.get(screenId, options?)`	One `ComputerScreen`.
`screens.resize(screenId, { width, height }, options?)`	Updated `ComputerScreen`.
`screens.delete(screenId, options?)`	`OKResponse`. The primary screen cannot be deleted.
`screens.connect(screenId, options?)`	Connection details: `screen_id`, `port`, `path`, `token`, `expires_at`, and optional `url`.

A screen record contains screen_id, display, width, height, vnc_port, and novnc_port. Before calling screens.connect(), enable public ingress with await sandbox.setIngress(true); the server returns 409 if ingress is disabled. Use the returned connection URL. Tokens expire, and each new connection request replaces the previous token for new connections. Treat tokens and token-bearing URLs as credentials.

See Computer REST for endpoint paths and errors.