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.

The local API

wet paint: New or experimental.Open as Markdown

benchd owns one host-local Unix socket and one private state store, and serves the same operations as the bench CLI over HTTP on that socket. The bench CLI is its only implemented client: pass --socket to any operation. There is no TCP listener (read from the source; no test asserts it, see the Security model). Never expose the socket through a TCP proxy.

The request and response shapes are proposed contract data, pinned from the suite’s contract repository. They are implemented and tested here; no suite product consumes them yet, and a shared response schema and published SDK for v1 are still pending.

Method Path What it is
GET /healthz A health check, open to any authorized peer (operator or reader). Returns the service name and API version.
POST /v1/operations Scalar (single-repository) operations, version superbench.v1.
POST /v2/operations Grouped workspace operations, version superbench.v2. See v2 operations.

Operation requests are POST with Content-Type: application/json; the health check is a GET. Three further v2 extensions exist in source but are proposed and disabled in the public Serve entry point: cancellation (an operation of cancel on /v2/operations), POST /v2/receipts/lookup for historical receipt evidence, and POST /v2/registrations/observe. No request can turn them on.

The daemon reads the caller’s uid from the kernel (SO_PEERCRED on Linux, LOCAL_PEERCRED on macOS); supplied identity headers grant nothing.

  • Operators (--operator-uids, by default the daemon’s uid and root) may run every operation. They are trusted to execute arbitrary commands as the daemon user.
  • Readers (--reader-uids) may run status and host_status only.
  • Anyone else gets forbidden.

The uid lists do not grant filesystem access by themselves: the socket is mode 0660 and its parent must not be group- or world-writable, so arrange a trusted local group. Lease tokens are holder capabilities, separate from the caller’s uid.

Growth operations (create, recover, lease, run, setup) require a request_id. The CLI generates one and prints it to stderr when --request-id is omitted; save it before issuing work whose reply might be lost.

  • Retry with the same ID and the same body. The same ID with a different body is a conflict.
  • IDs and responses are scoped to the authenticated uid.
  • A completed reply is cached durably and replayed exactly, including a historical lease token. A replayed token does not restore an ended lease; use status for the current state.
  • A retry while the operation is still running gets in_progress. A disconnected client does not cancel the work.
  • After a daemon restart, unfinished receipts become operation_in_doubt and are never run again automatically. Inspect status, stop the recorded execution if needed, checkpoint and release with the retained capability. Changing the ID is not reconciliation.

Checkpoint, release and stop do not create growth receipts, so a full receipt store never blocks reconciliation. Receipts are not collected; do not delete them to retry uncertain work.

SIGTERM cancels supervised runs, which fence before keeping their lease for inspection. SIGKILL can leave descendants alive; restart and stop --admin recover them from the durable execution scope. HTTP shutdown has a ten-second grace period, which does not release ownership of an unfinished operation. No timeout proves that a writer stopped.

Requests are at most 64 KiB. Every v1 response is at most 1 MiB; on v2, read-only responses are at most 1 MiB and durable growth responses at most 64 KiB. Unknown fields, duplicate keys, null optional values, trailing documents and invalid UTF-8 are refused. At most 64 concurrent connections, and 8 active operations by default (--max-active, 1 to 64). An overlarge status fails; query one key. There is no pagination.