Files and paths
State and data
Section titled “State and data”SuperBench keeps two directory trees apart: state (authoritative, private) and data
(mirrors and checkouts). They cannot overlap, including through symlinks. Use local filesystems and
the same --state and --data on every invocation. On a managed host they must be on different
filesystems, and the data tree is the dedicated XFS mount.
| Path | What it holds |
|---|---|
<state>/bench.db |
Versioned SQLite state, with FULL synchronous commits. Status reads it without migrating. |
<state>/service.db |
The daemon’s durable request receipts. |
<state>/benchd.sock |
The daemon’s socket, when --socket is not given. |
<state>/run-<execution id>.log |
A supervised run’s private, bounded output log. |
<state>/reap-<key>.json, <state>/archive-freeze-<key>.json |
Reap approval and archive permission journals. |
<data>/benches/<key> |
A bench’s checkout. |
<data>/mirrors/ |
Shared bare git mirrors, one per repository. |
<data>/store/ |
Shared caches: pnpm, npm, bun, playwright, go-build, go-mod. |
<checkout>/.bench/config.toml |
The repository’s settings. |
<checkout>/.bench/cache/ |
Checkout-local caches, when a repository chooses them. |
The defaults are <config dir>/superbench/state and <cache dir>/superbench/data, from Go’s user
config and cache directories (see bench CLI). Earlier prototype JSON state is
imported once on the next successful write and kept as a historical snapshot; SQLite is
authoritative from then on.
Git refs
Section titled “Git refs”| Ref | What it is |
|---|---|
refs/heads/bench/<key> |
A bench’s task branch, unless --branch names another. Checkpoints push here without force. |
refs/tags/superbench/pins/<bench_id>/<generation_id>/<member> |
A workspace checkpoint’s pin for one member. Never overwritten or deleted. |
refs/heads/superbench/checkpoints/<bench_id> |
A workspace’s checkpoint seal: commits holding only checkpoint.json. |
Mirror refreshes update only refs/remotes/origin/*.
The staged Linux installer’s paths
Section titled “The staged Linux installer’s paths”The repository’s Linux installer stages these for review and is used in drills on disposable hosts. It is not a supported installation.
| Path | What it is |
|---|---|
/usr/local/bin/bench, /usr/local/bin/benchd |
The CLI and the daemon. |
/usr/local/libexec/bench-quota |
The fixed-policy quota helper (the --quota-helper default). |
/usr/local/libexec/bench-payload |
Managed hosts only: the static payload helper. |
/usr/local/libexec/superbench-start |
The root-owned wrapper that starts benchd with its delegated cgroup. |
/etc/superbench/storage.json |
Root-owned managed storage policy: data root, ledger, owner uid and gid, byte and inode caps, reserves. |
/etc/superbench/benchd.env |
Root-owned daemon settings: operator and reader uids, active limit, intervals. |
/etc/sudoers.d/superbench |
Managed hosts only: sudo for the quota helper and the argument-free payload helper, nothing else. |
/var/lib/superbench/state |
The service account’s private state. |
/run/superbench/benchd.sock |
The service socket (parent 0750, socket 0660). |
/sys/fs/cgroup/superbench |
The default delegated cgroup root. The installed wrapper finds the service’s real cgroup instead. |
<ledger>/payload-retirements/<key>.json |
A reviewed Fresh retirement plan, root-owned 0600. |
The storage policy’s example uses /srv/superbench-data for the data mount and
/var/lib/superbench-quota for the privileged ledger; both are choices made at provisioning, not
fixed paths. Keep the ledger and state outside the bounded data filesystem.