Skip to content

Is My Machine Suitable

Tom Barber edited this page Nov 5, 2026 · 1 revision

Is my machine suitable?

The process backend runs an unmodified Linux program under Hermit. That needs a particular kind of machine. The sim and wasm backends need none of this and run on a Mac or on Linux: see Test-Logic-with-Wasm.

This page says what the process backend needs, how to check a machine before you spend time on it, and how to read the answers. It states what was measured or what the other pages already say. Where something was not tested it says so, and tells you how to test your own machine. The full version, with every output, is docs/guides/is-my-machine-suitable.md.

What it needs

Need Why
Linux on x86-64 Hermit runs only there. macOS and Apple silicon cannot run it
Hardware performance counters (a CPU performance monitoring unit, PMU) that the kernel can see Hermit counts hardware events to decide when to switch threads
kernel.perf_event_paranoid low enough for your user, or run as root Opening a counter
kernel.yama.ptrace_scope of 0 or 1, or run as root (2 needs root, 3 disables tracing) Hermit traces the program with ptrace
Linux 6.9 or newer (recommended) Older kernels take a slower ptrace path. Schedules are not affected; timeouts may be

The only configuration that has been measured is the one in the support matrix: Ubuntu 24.04.5 LTS, kernel 6.17.0-42-generic, one bare-metal host with an Intel Xeon E5-1410 v2 (Ivy Bridge) CPU, a pinned Hermit build, run as root. Passing the checks below means the prerequisites are met. It does not mean a program has been run under Hermit there, and it does not extend the matrix to your hardware.

Check a machine, in this order

Run these on the machine you plan to use, not on your laptop.

1. The read-only check. From a checkout of the repository:

bash scripts/install-hermit.sh check

It prints one line per prerequisite and exits 0 (met) or 1 (not met). It changes nothing. Inside a linux/amd64 Ubuntu 24.04 container on Docker Desktop on an Apple silicon Mac (run for this page, as root; the container is emulated):

Hermit host check (read-only: nothing on this machine is changed)
  platform       ok    Linux x86_64
  kernel         ok    6.12.54-linuxkit
  perf           ok    perf_event_paranoid = 2 (running as root)
  ptrace         ok    no Yama ptrace restriction
  pmu            FAIL  no hardware PMU registered
  container      note  running in a container: counters and ptrace are often blocked here
result: CANNOT RUN Hermit on this machine:
  - no CPU performance monitoring unit (PMU) is registered under /sys/bus/event_source/devices. Hermit needs hardware counters: use bare metal or a VM that exposes them.

On the Mac itself the first line is platform FAIL Darwin arm64 and the result says Hermit runs only on Linux. As an unprivileged user a root note is added: the measurements ran Hermit as root and running it unprivileged was not tested.

2. The authoritative probe, once Hermit is built (Installation):

hairspring doctor --process-backend

It opens a real hardware counter. Its last line is result: ok: ... (exit 0) or result: CANNOT RUN the process backend on this machine: with the reasons (exit 4). In the same container, with a build of main and no Hermit installed there, the perf counters row read FAIL no hardware PMU registered (perf_event_paranoid 2) and the reason ended with lowering perf_event_paranoid will not help.

3. A real run: hairspring doctor <target>, then hairspring test <target>. See Running-Your-Own-Software.

Why lowering perf_event_paranoid does not help

perf_event_paranoid decides who may open a counter. It cannot create one. When a line says no hardware PMU registered, the kernel lists no performance monitoring unit at all, so there is nothing to open whatever the setting. The kernel can answer with a permission error before it finds there is no hardware, which is why older builds of doctor advised lowering the setting on such a machine; the current one checks for a registered PMU first. If the PMU is there but a counter is still refused, the setting, a container profile or a security module may be in the way, and changing it is the machine owner's decision.

What to try, and what was tried

Environment What is known
Bare-metal Linux x86-64 host, as in the matrix The only configuration measured
Docker Desktop on an Apple silicon Mac, linux/amd64 container Tried: emulated, no hardware PMU registered
Docker Desktop on an Intel Mac or on Windows Not tested
Cloud virtual machines, bare-metal cloud instances Not tested. The quickstart says ordinary cloud VMs and containers were not tested and often do not expose the counters
A VM that passes the CPU's counters through Named in the quickstart as acceptable; not tested
GitHub-hosted runners Not tested
Any other CPU, kernel or distribution Not tested

To test your own machine, run steps 1 and 2. A pmu ok and a result: ok: are the first two hurdles; nothing here promises more.

Root or not

The measurements ran Hermit as root. Running it as an unprivileged user was not tested. This page makes no recommendation of its own; SECURITY.md has its advice on running a server and workers.

Next: Build-a-Linux-Executable, Testing-a-Service, Troubleshooting.

Clone this wiki locally