Skip to content
Not released yet. SuperBench is an experimental single-host prototype under active development. Nothing is released or supported for use yet. These docs describe themain branch and will be refreshed at the first release.

Quotas, mirrors and stores

wet paint: New or experimental.Open as Markdown

On a managed Linux host, each bench gets its own byte and inode hard caps on a dedicated XFS filesystem with enforcing project quotas, and the shared package store and shared mirrors get their own caps. A root-owned policy, /etc/superbench/storage.json, sets the ceilings and the reserve.

The caveat that travels with this: managed hosts only. Enforcement needs Linux, a dedicated XFS mount provisioned by the operator, root-owned policy and the privileged quota helper. On macOS and unmanaged hosts a quota request is recorded and not enforced. The test that exercises real XFS enforcement is skipped unless a disposable managed XFS fixture is present, so the evidence for enforcement is the repository’s recorded drills on loop-backed XFS images, not a host in use. Those recorded runs are historical: at least one names an uncommitted working snapshot of a feature branch, so they are not runs of the current commit.

What managed storage does:

  • Admission. Create, recover, new leases and supervised runs check free-space reserves on the data and state filesystems before starting work (--min-data-free, --min-state-free). Managed admission also rechecks quota enforcement through the helper.
  • Fixed-policy allocation. The helper accepts logical allocations only: apply bench KEY [BENCH_BYTES], apply shared store, apply shared mirrors, and release bench KEY PROJECT_ID. Every allocation is journaled before it touches the filesystem, so a retry after a lost reply reuses its original reservation. Project IDs start at 10000 and are never reassigned.
  • Conservative accounting. Total bench caps plus the shared caps and the reserve cannot exceed the filesystem, for bytes or inodes, and unfinished allocations still count.
  • Bounded run logs: per-command output (--max-log-bytes), the total retained and reserved log bytes (--max-logs-bytes) and the number of logs (--max-log-files).

A repository can ask for a smaller bench in .bench/config.toml with [quota] size = "4G". The request is read from the immutable source commit at creation, and the root policy’s BenchBytes is both the maximum and the default. Changing the request later does not resize a bench: ordinary acquisition refuses the mismatch, while checkpoint, release and repair stay available. See Repository settings.

Benches start from a shared bare mirror per repository. Ordinary lease, run and explicit setup refresh it before granting ownership or launching task code:

  • The refresh first checks the mirror’s physical path, its bare-repository identity and its single registered origin, and that the checkout still shares that mirror and names its task branch.
  • The fetch updates and prunes only refs/remotes/origin/*, atomically. Local branches, tags, HEAD, the index, dirty and untracked files and ignored output are preserved. It does not pull, merge, rebase or reset a task branch.
  • A failed or cancelled refresh grants no ordinary lease. A missing or changed mirror is refused, not recloned. bench lease-repair stays available because it skips the refresh.
  • The deadline is --mirror-timeout, two minutes by default.

Partial mirror clones are staged and published atomically; abandoned staging directories are kept under their own reviewed collection (bench mirror-clones).

.bench/config.toml chooses, per tool, whether a cache is shared across benches or kept inside the checkout:

Setting Shared, under data Checkout-local Environment
pnpm store/pnpm .bench/cache/pnpm npm_config_store_dir; clone imports
npm store/npm .bench/cache/npm npm_config_cache
bun store/bun .bench/cache/bun BUN_INSTALL_CACHE_DIR
playwright store/playwright .bench/cache/playwright PLAYWRIGHT_BROWSERS_PATH
go store/go-build, store/go-mod .bench/cache/go-build, .bench/cache/go-mod GOCACHE, GOMODCACHE

All five default to shared. A repository cannot name an arbitrary cache path. Setup hooks and supervised commands inherit these paths; a shell opened after a cooperative lease does not. Checkout-local caches count against the bench’s cap and should be ignored in .gitignore (.bench/cache/), or their files will block checkpoint and release.

The shared package store is part of the managed XFS setup above and shares its limits. Collecting old shared caches and mirrors is not built.