Skip to content
Docs menu

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.

View .md

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/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

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