Headless browser launcher

headbox runs a headless browser that leaves nothing behind.

headbox installs a pinned chrome-headless-shell and runs it inside bubblewrap, with every writable path in a size-capped tmpfs. Tests and coding agents talk to it over the Chrome DevTools Protocol; when headbox ends, even by kill -9, the browser and its files are gone.

go install ubunatic.com/headbox@latest

Install Browse the source

Project snapshot · measured 2026-10-26

Key facts

Commits 10Last commit 2026-10-22 Source receipt ↗ Commits · 7 days 10 Source receipt ↗ Tickets closed 2 / 2 Source receipt ↗ Studies 1 Source receipt ↗

12-week commit activity

2026-10-26

Aug 3

Aug 10

Aug 17

Aug 24

Aug 31

Sep 7

Sep 14

Sep 21

Sep 28

Oct 5

Oct 12

Oct 19

View 12-week data table

Week starting	Commits
2026-08-03	0
2026-08-10	0
2026-08-17	0
2026-08-24	0
2026-08-31	0
2026-09-07	0
2026-09-14	0
2026-09-21	0
2026-09-28	0
2026-10-05	0
2026-10-12	0
2026-10-19	10

Key Features

Installs a pinned, sha256-checked chrome-headless-shell.
Runs it in bwrap with a tmpfs profile and hands tests and agents a CDP URL.
Stops an agent browser after an idle period.

Verified Engineering Milestones

Research of nine headless browser setups with kill -9 canaries (ubunatic.com #095)
Pinned install, bwrap sandbox and exec/serve with kill -9 tests (#001, 6b6db83)
v0.1.0 release with signed binaries and the ubunatic.com/headbox vanity path (8861575)

Stack

Go 1.26, Cobra, bubblewrap, chrome-headless-shell, YAML + JSON Schema, GoReleaser

Features

One binary, one pinned browser, no leftovers

Pinned and checked

headbox install downloads the chrome-headless-shell version pinned in the binary and checks its sha256 before unpacking.

Kernel cleanup

The browser runs in its own PID namespace as a direct child of headbox; when headbox dies, the kernel ends the whole tree.

Nothing on disk

Profile, caches, /tmp and /dev/shm live in size-capped tmpfs mounts that vanish with the sandbox.

Any CDP client

Puppeteer, Playwright's connectOverCDP, chromedp or chrome-devtools-mcp connect through CDP_URL.

Fast

headbox exec -- true takes about 0.2 s, including the browser start.

Idle stop

headbox serve keeps a browser for agents and stops it after a period without CDP connections.

Usage

Wrap a command or serve a browser

headbox install                  # once: download + sha256-check the pinned browser
headbox exec -- node check.mjs   # browser up, CDP_URL set, browser gone when the command ends
headbox exec -- sh -c 'curl -s "$CDP_URL/json/version"'

# a browser for coding agents, on a fixed port, gone after 30 idle minutes
headbox serve --port 9333 --idle 30m &
chrome-devtools-mcp --browserUrl http://127.0.0.1:9333

Command	What it does
`install [--zip FILE]`	Download the pinned browser, check its sha256, unpack it to `~/.local/share/headbox/`
`exec -- CMD`	Start the browser, run CMD with `CDP_URL`, `HEADBOX_WS_URL` and `HEADBOX_CDP_PORT`, exit with its code
`serve [--idle 15m]`	Keep a browser for agents until idle, Ctrl-C or SIGTERM
`path`	Print the browser's install dir
`version`	Print the headbox and browser versions

Sandbox

What the browser sees

/tmp, /dev/shm

tmpfs, 256 MiB each.

$HOME

tmpfs, 512 MiB, for the profile and caches.

/usr, /lib64, /etc

Read-only from the host.

/opt/browser

The browser dir, read-only.

network

Shared, so pages load and the CDP port is reachable on 127.0.0.1.

Chrome's own sandbox stays on inside bwrap. Sizes, browser version, URL and sha256 live in spec/browser.yaml, embedded in the binary.

Install

Install with Go

Requires Linux with unprivileged user namespaces and bwrap (dnf install bubblewrap or apt install bubblewrap), and Go 1.26 or newer to build. Release binaries for x86_64 and aarch64 are on Codeberg.

go install ubunatic.com/headbox@latest
headbox install

Engineering story

Why a browser needs a box

Read the headbox engineering story, which compares nine headless browser setups and what each leaves behind after kill -9.

Project details

Stack

Go 1.26, Cobra, bubblewrap, chrome-headless-shell, YAML + JSON Schema, GoReleaser

Milestones

Research of nine headless browser setups with kill -9 canaries (ubunatic.com #095) · Pinned install, bwrap sandbox and exec/serve with kill -9 tests (#001, 6b6db83) · v0.1.0 release with signed binaries and the ubunatic.com/headbox vanity path (8861575)

Source

https://codeberg.org/ubunatic/headbox ↗

Architecture

Layer composition

Terminal: CLI
Desktop: Linux, bwrap, /proc
Inference / AI: —
Containers / VM: user namespaces
Web: Chrome DevTools Protocol

Engineering story

headbox: the story behind the project

The ubunatic.com site checks ran a Flatpak Chromium. On 2026-10-22 its sandbox /tmp , which lives in RAM under /run/user/1000 , held 2.4 GB of old browser profiles and filled the runtime dir; an unrelated tool then failed with "no space lef…

Read the engineering story

Measurement source · 2026-10-26

Verification receipts

Commits: 10 · Last commit 2026-10-22
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Commits · 7 days: 10
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Tickets closed: 2 / 2
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Studies: 1
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
12-week commit activity
git rev-list --count --since=<Monday> --until=<Sunday> HEAD
12 latest complete ISO weeks; weekly values are from spec/metrics.yaml.