---
title: The venom-computer host image
description: Build and run the host container for Venom Computers, with venom-seatd, the seat endpoints, the environment it reads, how to run it locked down, and what a seat costs in memory.
section: deploy
order: 85
audience: [operator, builder]
sources: [docs/adr/0078-venom-computers.md, deploy/computer/Dockerfile, deploy/computer/README.md, services/go-orchestrator/cmd/venom-seatd, services/go-orchestrator/internal/seatd]
features: [orchestrator.ops]
---

A Venom computer is a browser an agent owns: a Chromium profile on disk (cookies, logins, history), a work
directory, and, while the agent is using it, one Chromium process. A **host** is one container that holds up to 25
seats by default. The image is `venom-computer`; its entrypoint is `venom-seatd`, a small Go program that owns the
seats in the container. The desktop daemon starts hosts and talks to seatd; you do not normally run the image by
hand, but you can, and this page is the reference for it.

Nothing here calls out. The image build downloads Debian packages; at run time the only traffic is Chromium to the
sites an agent visits, through the proxy you give each seat.

## Build it

```sh
make computer-image          # venom-computer:dev, from deploy/computer/Dockerfile
```

A daemon installed from a release has no source tree: its `share/computer/` holds the same Dockerfile and a
prebuilt `venom-seatd`, and enabling Computers builds from there with `--build-arg SEATD=prebuilt`, which takes
seatd from the build context instead of compiling it (BuildKit builds only the stage it needs).

The image is Debian slim with Chromium from Debian at a pinned version (`CHROMIUM_VERSION` in the Dockerfile),
Noto CJK and emoji fonts, `tini` and `venom-seatd`. Debian removes a superseded Chromium from its security archive,
so bump the pin on each Chromium security release.

## Run it

```sh
docker run -d --name host1 --network venom-computers \
  --read-only --tmpfs /tmp:rw,mode=1777 -v host1-data:/data \
  --cap-drop=ALL --cap-add=SETUID --cap-add=SETGID --cap-add=CHOWN \
  --cap-add=DAC_OVERRIDE --cap-add=FOWNER --cap-add=KILL \
  --pids-limit=2048 --memory=16g --cpus=4 \
  -e SEATD_TOKEN="$(openssl rand -hex 32)" venom-computer:dev
```

Do not publish port 8800. seatd listens on the host's internal Docker network and the daemon is its only client.
Every request carries `Authorization: Bearer <SEATD_TOKEN>`; without it seatd answers 401.

seatd is the only process that runs as root. It gives each seat its own Linux user (uid 20000 to 29999, home
`/data/seats/<id>` mode 0700) and drops to that user before it starts Chromium, so one seat cannot read another's
profile. Chromium runs with no capabilities. The six capabilities above are what seatd needs for that; everything
else stays dropped.

### Chromium's sandbox

Chromium's own sandbox needs user namespaces. Docker's default seccomp profile refuses them without
`CAP_SYS_ADMIN`, so on a stock `docker run` seatd detects this, starts Chromium with `--no-sandbox` and logs a
warning for each seat; `GET /status` reports `"sandbox": false`. The container, the per-seat user and the dropped
capabilities are then the boundary. To keep Chromium's sandbox on, run with a seccomp profile that allows
`unshare` and `clone` with user namespaces (Chromium's documented `chrome.json`); seatd probes at start and leaves
the sandbox on. `SEATD_SANDBOX=on` refuses to fall back, `off` always passes `--no-sandbox`.

## What seatd reads

| Variable | Default | |
|---|---|---|
| `SEATD_TOKEN` | required | the bearer token every request must carry |
| `SEATD_LISTEN` | `:8800` | listen address |
| `SEATD_DATA` | `/data` | seats live in `<data>/seats/<id>` |
| `SEATD_CHROMIUM` | `chromium` | Chromium binary (the image sets `/usr/bin/chromium`) |
| `SEATD_UID_RANGE` | `20000-29999` | the uids a start request may name |
| `SEATD_IDLE_AFTER` | `30s` | quiet time (no DevTools traffic, no viewer) before a seat reports `idle` |
| `SEATD_SANDBOX` | `auto` | `auto`, `on` or `off` |

Chromium gets a minimal environment: seatd's token never reaches it. It also starts with the background network
features off (component updates, sync, pings, crash reports).

## The endpoints

| Endpoint | Does |
|---|---|
| `POST /seats/{id}/start` | create the seat's directories if new and launch Chromium; idempotent. Body `{kind, uid, viewport, locale, timezone, proxy}`; `kind` is `browser` |
| `POST /seats/{id}/stop` | `{"mode":"hibernate"}` closes Chromium gracefully (`Browser.close`, then SIGTERM, then SIGKILL) and keeps the profile; `{"mode":"destroy"}` also removes the seat's directories |
| `GET /seats/{id}/cdp` | WebSocket proxy to the seat's DevTools browser endpoint; the only way in |
| `GET /seats/{id}/screencast` | WebSocket: JPEG frames out (binary messages), `Input.dispatch*` events in; `?quality=` (1-100, default 50), `?fps=` (1-30, default 12: Chromium is asked for every Nth frame and each viewer is held to its own fps), `?maxWidth=`, `?input=1` to allow input. One screencast per seat is shared by its viewers and stops when the last one leaves |
| `GET /seats/{id}/thumbnail` | one JPEG, at most 320 px wide |
| `GET /status` | per seat: state (`cold`, `starting`, `active`, `idle`, `hibernating`), pid, memory, CPU, last activity, viewers, connections; host totals |
| `POST /seats/{id}/fill` | not implemented yet: answers 501 |

Several clients can connect to one seat's `/cdp` at once (a shared seat). Each connection gets its own DevTools
connection to Chromium, so command ids never collide, and records who it is from the `X-Venom-Client` header (or
`?client=`). A crashed Chromium marks the seat `cold` with `crashed: true` and the last stderr in `error`; a new
`start` brings it back from the profile on disk.

## What a seat costs

`/status` reports three memory figures per seat. `rss_bytes` sums each process's resident set and counts the shared
Chromium and library pages once per process, so it is several times too high. `anon_bytes` (private and shared
memory only, from `/proc/<pid>/status`) is what one more seat adds, and is the figure to size a host by.
`pss_bytes` appears only where `/proc` lets seatd read `smaps_rollup`. The orchestrator sizes admission by it (summed RSS counts a seat's ~14 Chromium processes' shared pages once each, about 5x over) and falls back to `rss_bytes` where it is absent.

Measured with the image above on a 24-thread Linux box, Chromium 156 headless, container cgroup memory (`docker
stats`):

| | Memory |
|---|---|
| seatd alone | 4 MiB |
| one idle `about:blank` seat | about 170 MiB over seatd |
| the same seat on a heavy page (250 MiB of JavaScript heap, a 20,000-node DOM) | about 520 MiB |
| three seats, one heavy | 884 MiB in total |
| resume of a hibernated seat to its first DevTools command | 200 to 300 ms |
