kosa8 docs

Guides / kosa8 Cloud / Desktop and computer use

Desktop and computer use

The kosa8-desktop image gives a sandbox a screen. It runs a virtual display with a light window manager and Chromium. A person can watch or take over through noVNC in a browser, and an agent can drive Chromium over the DevTools protocol (CDP). It can also take screenshots and send clicks and keys from an ordinary exec.

PortWhat
6080noVNC: the desktop in a web page. Open it as a preview URL.
9222Chromium's CDP, for Playwright, Puppeteer or browser-use, through a preview URL.

Inside the image: Debian 13, Xvfb, fluxbox, x11vnc, noVNC with websockify, Chromium, xdotool and scrot. Every package is pinned in images/desktop/versions.env.

1. Create a persistent sandbox from the image

Create it persistent, so the desktop keeps running between commands. Use at least 2 vCPU and 4 GiB, since Chromium is heavy.

curl -s -X POST https://api.kosa8.com/v1/sandboxes \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"size":"2x4","persistent":true,"image":"ghcr.io/azmxai/kosa8-desktop:13"}'
# 202 {"sandbox":{"id":"sbx_…","state":"creating",…}}  then running once the image is pulled

In production, name a dated tag such as 13-20261114.1 instead of the moving 13, so the image cannot change under you.

2. Start the desktop

curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/exec \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"cmd":["kosa8-desktop","start"]}'
# {"exit":0,"stdout":"desktop ready: noVNC on :6080, CDP on :9222, screen 1280x800, DISPLAY :99\n",…}

Running start again only starts the parts that have stopped. Set KOSA8_SCREEN (for example 1920x1080) and KOSA8_START_URL in the exec's env to change the screen size and first page. kosa8-desktop status --json reports each part, and kosa8-desktop stop ends them all.

3. Watch it, or take over

curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/previews \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"port":6080}'
# {"preview":{"url":"https://6080-….<preview domain>/?kosa8_preview=eyJz…",…}}

Open url in a browser and press Connect. The VNC server itself only listens inside the sandbox, so this private preview, with its signed link, is the only way in. Anyone who has the link can use the mouse and keyboard until the link expires. Use …/previews/6080/rotate to end every link at once.

4. Drive Chromium over CDP

curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/previews \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"port":9222}'
# {"preview":{"host":"9222-….<preview domain>","token":"eyJz…",…}}
// Playwright (Node). The token goes in a header on every request, the WebSocket included.
import { chromium } from "playwright";
const browser = await chromium.connectOverCDP(`https://${preview.host}`, {
  headers: { "X-Kosa8-Preview-Token": preview.token },
});
const page = browser.contexts()[0].pages()[0] ?? await browser.contexts()[0].newPage();
await page.goto("https://example.com");

Chromium listens on 127.0.0.1 inside the sandbox, and only accepts requests addressed to localhost or an IP address. kosa8-cdp-proxy sits on port 9222 in front of it. It readdresses each request to Chromium, drops the preview's token and cookie, and rewrites the WebSocket URLs that /json/version answers with to wss:// on the preview's own address, so clients connect back through the preview.

Never open port 9222 with "public": true. CDP has no login of its own: whoever reaches it controls the browser, including its cookies and every site it is signed in to.

5. Screenshots and input from an exec

curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/exec \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"cmd":["kosa8-desktop","screenshot","--base64"]}' | jq -r .stdout | base64 -d > screen.png
CommandDoes
kosa8-desktop screenshot [FILE] [--base64]A PNG of the whole screen, saved to FILE (default /tmp/kosa8-desktop/screen.png), or printed as base64
kosa8-desktop click X Y [BUTTON]Move to X,Y and click (1 left, 2 middle, 3 right)
kosa8-desktop move X YMove the pointer
kosa8-desktop type TEXTType text
kosa8-desktop key KEY…Press keys, in xdotool names: Return, ctrl+l, alt+Tab
kosa8-desktop scroll up|down [N]Scroll N notches (default 3)
kosa8-desktop sizeThe screen size, such as 1280x800

These are the actions a computer-use model asks for (screenshot, click, type, key, scroll), so a tool loop can map each one to an exec. xdotool is also there to use directly, with DISPLAY=:99.

Limits