The venom-computer host image
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.
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
make computer-image # venom-computer:dev, from deploy/computer/DockerfileA 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
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:devDo 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 |