Browse the documentation

Early preview

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

KeyAccepted formsMeaning
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.

ModeGuaranteeCPUMemory
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.
flexibleA 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 strict mode 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 code 69.
  • 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

Platformstrict CPUstrict memoryflexible
Linuxcgroups v2 cpu.max on a dedicated cgroup holding the whole treecgroups v2 memory.max with memory.swap.max = 0 and memory.oom.group = 1cpu.weight and memory.high, with cpu.max and memory.max set to burst_limit when configured
WindowsJob Object CPU rate control with a hard capJob Object job memory limitJob Object CPU rate weight or minimum and maximum rate, and memory notification limits
macOSA 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 systemd manager. 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, strict mode uses the governor only when the manifest sets resources.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

KeyBounds
resources.max_pidsThe number of processes in the tree. A guest that exceeds the PID quota is stopped with exit code 70.
resources.max_open_filesThe 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.