oomwrap
oomwrap is a Linux command-line tool for process-scoped memory protection. It checks available RAM and swap before it starts one command, then stops that command's process group if either configured floor is crossed.
Use it for any local workload that can exhaust memory, such as a large build,
renderer, data conversion, model load, or inference server. oomwrap complements
machine-wide tools such as earlyoom; it does not replace them.
Install
Install oomwrap from GitHub:
For development from a local checkout:
Check the machine and installation:
Run a command
Choose RAM and swap floors for the machine and workload:
oomwrap launches the child in its own process group. It forwards terminal
signals and returns the child exit code on a normal exit. If memory pressure
crosses a floor, oomwrap sends SIGTERM, waits for the configured grace period,
and then sends SIGKILL to the remaining process group. A pressure stop returns
exit code 137.
Inference example
Inference profiles recognize common local engines and require active earlyoom
by default:
Supported profiles are auto, vllm, llama-cpp, sglang, trtllm, tgi,
and generic. Use generic for other commands. Use --allow-no-earlyoom only
for tests or controlled machines with another machine-wide safety mechanism.
Event logs
Write launch, refusal, exit, and memory-pressure events as JSON Lines:
Inference command wrappers
PATH shims let existing inference commands run through oomwrap without changes to each script:
This installs shims for common inference tools under ~/.local/bin. Put that
directory before the real runtime directory in PATH.
Remove the shims with:
Use wrap when a benchmark or script calls a fixed runtime path:
This moves the original executable to vllm.real and places an oomwrap-managed
wrapper at the original path. Restore it with:
Exit behavior
- Child exits normally: return the child exit code.
- Required
earlyoomis missing: return3. - A preflight memory or swap floor fails: return
4. - oomwrap stops the group for memory pressure: return
137. - Configuration or supervision fails: return
2.
Agent skill
The canonical memory-safe-launch skill is in
.agents/skills/memory-safe-launch. It
describes a safe launch procedure for general memory-heavy commands and adds
checks for local model inference.
The binary exposes the skill through Skillflag:
The skill is embedded in the binary, so these commands also work after a
cargo install without the source checkout.