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.
| Port | What |
|---|---|
| 6080 | noVNC: the desktop in a web page. Open it as a preview URL. |
| 9222 | Chromium'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
| Command | Does |
|---|---|
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 Y | Move the pointer |
kosa8-desktop type TEXT | Type 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 size | The 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
- The desktop runs as the user
desktop, not root. Chromium uses its own sandbox where the kernel allows unprivileged user namespaces. Where it does not, Chromium starts with--no-sandbox, inside the sandbox's VM, and says so in/tmp/kosa8-desktop/chromium.log. - Nothing is recorded: there is no session video yet. Take screenshots if you need a trail.
- Sleep keeps memory, so the desktop comes back on wake where it was. If
kosa8-desktop statusreports a part down,kosa8-desktop startrestarts only that part. - Egress controls apply to the browser like any other program. An allow list that leaves out the sites the agent visits will stop it.