# 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 status` reports a part down, `kosa8-desktop start` restarts 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.

---
Source: https://docs.kosa8.com/guides/cloud-desktop/
