saphan/saphan-probe repository overview

⁠saphan-probe

A one-shot capability probe: it answers "can this host actually start a container, and what does one see once it is running?" — and nothing else.

It is FROM scratch with a single static binary as its only file. No shell, no package manager, no utilities. That is not minimalism for its own sake: the probe exists to measure the runtime, so anything added to the image would make it measure a different container from the one real workloads get.

Runs as 65534:65534 (nobody). Linux only.

⁠What it prints

SAPHAN-PROBE-RAN
SAPHAN-VM-CPUS=8
SAPHAN-VM-MEMORY-BYTES=16769654784
SAPHAN-PROBE-OK

SAPHAN-PROBE-RAN and SAPHAN-PROBE-OK are fixed markers: the first says the image started, the second says it finished its reads. If the reads fail you get SAPHAN-PROBE-ERROR=<reason> instead of -OK, and no numbers — an absent marker is a result, never a silence to interpret.

⁠Usage

docker run --rm saphan-probe

Exits 0. Parse the markers, not the line order.

⁠⚠ What the two numbers actually are

They come from sched_getaffinity and sysinfo(2), so read them as facts about the kernel the container is running on, not as its limits:

• CPUS follows the CPU set the container is pinned to. It does not reflect a CPU quota: a container limited to 0.5 CPU on an 8-core host still reports 8.
• MEMORY-BYTES is the kernel's total RAM. Under a normal runtime (runc) that is the host's memory, not the container's memory limit. Under a VM-backed runtime (Kata, Firecracker) it is the microVM's.

⇒ Use it to tell apart "containers do not run here", "they run on the host kernel", and "they run in a VM of this size". Do not use it to read back a limit you set — for that, read the cgroup.