fherma-runner

Takes measurement jobs from a FHERMA platform and reports what happened.

uv tool install fherma-runner        # or: pipx install fherma-runner
fherma-runner --api https://fherma.io --name bench-01 --token fhr_...

A command line tool belongs in an environment of its own, and on macOS it has no choice: the system Python has no pip on the path at all, and Homebrew's is marked externally managed so installing into it is refused. uv tool and pipx both make that environment and leave fherma-runner on the path, which is the part pip install --user does not do.

Neither installed? One line, and nothing else on the machine changes:

curl -LsSf https://astral.sh/uv/install.sh | sh

Check what you got:

$ fherma-runner --version
fherma-runner 0.2.0 · python 3.13.4

The token comes from the platform, is good for an hour and is spent once: the first start exchanges it for this machine's own key and keeps that in ~/.fherma-runner. Every start after the first needs no token.

Every start says what the machine is now, so a server that was re-provisioned is matched on what it is rather than on what it was.

What it needs

An interpreter and docker. There are no dependencies: everything here ships with Python, and docker is called as a command.

What it declares

Hardware, and only hardware — cores, memory, architecture, CPU features, an accelerator and its driver. It does not declare libraries or images, because the environment a job runs in is not a property of a machine: it arrives with the job, pinned to a digest.

fherma-runner --describe

prints what it would report, and stops.

What it does with a job

jobs/<id>/
├── bundle/     the specification's bundle, unpacked
├── solution/   the repository at the commit, and its build
└── points/
    └── p000/   one point at a time, deleted once reported

Per point: the bundle makes the cases, the solution answers them, the bundle judges the answers. Three containers, and the solution is never given the directory holding the expected answers.

Options

--api           where the platform is                  FHERMA_API
--name          what to call this machine              FHERMA_RUNNER_NAME
--token         an invitation, spent once for a key
--interval      seconds between polls                  3
--once          take one assignment, then stop
--describe      print what this machine is, and stop
--version       what is installed, and on what
--re-register   forget the key and join again

The --speed, --fail-rate, --build-seconds and --point-seconds options belong to the half that is still pretended, and go away with it.

Stopping

The platform stops a runner by refusing its heartbeat. It then drops everything at once and sends nothing: finishing the work and reporting it would be reporting into a result somebody else now owns.

If a runner goes quiet instead, its lease lapses, the run is marked expired and the job goes to another machine.

Licence

Apache-2.0.