CPU and memory capping
Capping is a native function of the Executor, independent of sandboxing. You state at build time how much CPU and memory the workload may use. The limits are sealed into the signed policy and enforced by oee-stub on the complete guest process tree, every worker and descendant included, whether or not the sandbox is enabled.
resources:
cpu:
limit: "10%"
mode: "strict"
memory:
limit: "10%"
mode: "strict"
max_pids: 64
max_open_files: 4096
allow_governor_fallback: false
Limits: a share of the machine or an absolute amount
| Key | Accepted forms | Meaning |
|---|---|---|
resources.cpu.limit | "10%" | A percentage of the logical CPU capacity of the machine the binary runs on. 10% of a 10-core machine is 1.0 core; 10% of a 5-core machine is 0.5 core. Greater than 0% and at most 100%. |
"1vcpu", "0.5vcpu", "2" | An absolute number of CPU cores, used exactly as given on every machine. | |
resources.memory.limit | "10%" | A percentage of the physical memory of the machine the binary runs on. 10% of a 24 GB machine is 2.4 GB. |
"10GB", "512MB", "2GiB" | An absolute amount of memory, used exactly as given on every machine. |
- Capacity base. Percentages resolve against the capacity actually available to the binary: the host's logical CPU count and physical memory, reduced to the enclosing container's own CPU and memory limits when the binary runs in a container. A
"10%"cap in a container limited to 4 cores resolves against 4 cores, not the host's 64. - Resolved once, then fixed. Limits are resolved exactly once at supervisor startup, recorded in the startup audit event, and never recomputed for the life of the instance. CPU hot-plug or memory ballooning after startup does not move the cap.
- Unsatisfiable limits. An absolute limit larger than the capacity base is clamped to the base, with a warning. A limit that resolves below the minimum the platform can enforce is a startup error.
Modes: strict and flexible
Each resource has its own mode, so a workload can have a strict memory cap and a flexible CPU cap.
| Mode | Guarantee | CPU | Memory |
|---|---|---|---|
strict (default) | A hard ceiling that is never exceeded and never changed. | The kernel throttles the process tree so its total CPU time never exceeds the limit in any enforcement period. | The tree can never hold more memory than the limit. An allocation that would cross it ends in an out-of-memory termination inside the tree, and the Executor stops the workload with exit code 70. Swap cannot be used to exceed the limit. |
flexible | A soft target with optional bursting. | The limit is a proportional share under contention; the tree may use idle CPU beyond it, up to burst_limit when one is set. | Above the limit the kernel throttles and reclaims the tree's memory instead of terminating it; burst_limit, when set, is a hard ceiling. |
Strict means strict
- Never silently downgraded. In
strictmode the supervisor must hold a kernel-enforced hard limit before the guest starts. If the host offers no such primitive to the current user, the binary refuses to launch and exits with code69. - Immutable at run time. A sealed cap cannot be raised or disabled by environment variables, command-line arguments, the local control socket or a remote exit-event response. Changing it requires a new signed build.
- One budget for the whole tree. Caps apply to the cgroup or Job Object that contains the whole tree, not to single processes. Forked workers and detached daemons share one budget and cannot evade it.
Enforcement on each platform
| Platform | strict CPU | strict memory | flexible |
|---|---|---|---|
| Linux | cgroups v2 cpu.max on a dedicated cgroup holding the whole tree | cgroups v2 memory.max with memory.swap.max = 0 and memory.oom.group = 1 | cpu.weight and memory.high, with cpu.max and memory.max set to burst_limit when configured |
| Windows | Job Object CPU rate control with a hard cap | Job Object job memory limit | Job Object CPU rate weight or minimum and maximum rate, and memory notification limits |
| macOS | A supervisor CPU governor (duty-cycle control of the process group) | A supervisor memory governor (process-tree footprint sampling, with termination at the limit) | The same governors with soft thresholds |
- Rootless Linux. The supervisor obtains a writable delegated cgroup without root: its own delegated subtree when one exists, otherwise a transient scope from the user's
systemdmanager. Inside containers it uses the container's cgroup when that is writable. - Governor tier. Where no kernel hard limit exists for a process tree (macOS, and Linux hosts with no delegated cgroup), a supervisor-side governor enforces the cap by sampling the tree and pausing or terminating it, within a documented sampling tolerance. On Linux,
strictmode uses the governor only when the manifest setsresources.allow_governor_fallback: true; by default it refuses to start. The selected enforcement tier is always printed in the startup audit event.
Accuracy
The design targets, with kernel enforcement: the CPU usage of the capped tree never exceeds the limit by more than 2% over any one-second window, and memory usage never exceeds the limit at all. Percentage limits resolve to exactly the documented values, for example 10% of 10 cores is 1.0 core.
Other quotas
| Key | Bounds |
|---|---|
resources.max_pids | The number of processes in the tree. A guest that exceeds the PID quota is stopped with exit code 70. |
resources.max_open_files | The file descriptors per process. |
Usage metrics
The supervisor continuously reads the tree's CPU and memory usage from the same primitives that enforce the caps. These metrics feed oee status, the heartbeat payload of the HTTP poller ({{memory_rss_mb}}, {{cpu_usage_percent}}), utilization exit events and the auto-scaler.
Caps and utilization exits
A utilization exit event is a planned, state-preserving stop that you can trigger before a cap is reached, for example when memory stays above 95% of the cap for five minutes. A strict cap is the hard ceiling the kernel enforces regardless.