An agent's test command spawns many child processes inside a devcontainer, and we want to know which limit stops those processes from consuming the rest of the workstation's resources.
The answer depends on the resource and on the operating system that enforces the limit. A container's memory ceiling, the Linux VM's allocation, and the number of agent jobs running at once each govern a different kind of demand. If you run coding agents in devcontainers, this article shows you how to tell those boundaries apart and which one to inspect when a job slows down or dies. The setup is a Linux VM on macOS (Docker Desktop, or OrbStack for the measurements below) that runs the containers; the VM layer applies only where such a VM sits between the host and the containers.
Linux containers share a kernel, and a mount or access to the Docker daemon can expose resources beyond a container's normal view. The host may become unresponsive even with container limits in place, because each limit bounds one container, nothing caps the sum of all containers below the VM allocation, and a container started without flags gets no limits at all.
The post takes five steps:
- Locate the kernel that enforces a container's limits.
- Separate the CPU, memory, and task-count controls, since each fails in a different way.
- Inspect what each container received, without exhausting a limit.
- Read the cgroup event counters before diagnosing a failure.
- Match each concern to the boundary that controls it.
Locate the enforcing kernel
The first question is which kernel enforces a container's limits, because on a Mac it is not the host kernel.
On macOS, Docker Desktop runs Docker Engine inside a Linux VM, and container processes run under that VM's Linux kernel. The Mac runs its own operating system, while Docker Desktop components move network traffic and shared-file operations across the VM boundary. Numbers read inside a container describe the VM's Linux kernel, not the Mac.
Inside that environment, namespaces scope views such as process IDs and network interfaces, and control groups (cgroups) account for and constrain the resources assigned to groups of tasks. A task is a thread, so one process with many threads counts as many tasks. Docker's security documentation treats namespaces, cgroups, the daemon's attack surface and container profiles as separate concerns.
Docker Desktop's resource settings set the CPU and memory available to the whole Linux VM.
Every workload in it shares that allocation, which sits apart from any one container's limits and from what native Mac applications use.

Figure text
macOS host, Linux VM, container, and process form four nested boundaries. The VM's Linux kernel enforces the container's resource controls. We check mounts and daemon access separately.
- Four boundaries, one enforcing kernel
- Enforced by the VM's kernel (lamp)
- Trust exposure, a separate check
- Limits apply inside the VM's allocation. What a mount or daemon access exposes is a separate trust check.
- 1 Who enforces the container's limits
- 2 Container ceilings sit inside the VM's share
- 3 Shared files, check separately
- 4 Daemon access, check separately
- Agent process
- Container ceilings
- Docker daemon
- VM's Linux kernel
- VM allocation
- Host files
- Enforced here
- Mac host
- Linux VM
- Container limits
- Shared files and access to the Docker daemon reach past the container. Limits do not cover them, so we check them separately.
Sources: [1] Control Group v2 - The Linux Kernel documentation; [2] Docker Engine security | Docker Docs; [3] Change your Docker Desktop settings | Docker Docs; [4] Networking on Docker Desktop | Docker Docs; [5] Define services in Docker Compose | Docker Docs.
See how CPU, memory, and task limits fail differently
A CPU quota caps how much CPU time a container can use per scheduling period, and once the container uses up that allowance, runnable work gets throttled until the next period.
The period defaults to 100 ms, so --cpus=2 allows 200 ms of CPU time in every 100 ms period.
The quota doesn't reserve a physical core.
Docker has a separate CPU-set control for pinning CPUs, and CPU shares set a relative weight under contention without imposing a hard ceiling.
Three Docker flags set the memory limits used here, each in its own cgroup file:
--memorywrites the hard limit tomemory.max.--memory-reservationwrites a soft reservation tomemory.low.--memory-swapsets the memory-plus-swap total, and the swap part lands inmemory.swap.max.
Docker leaves memory.high at its default of max, so nothing throttles a container below its hard limit unless we set it ourselves.
Docker separates hard limits from soft reservations in its memory resource reference.
Under different conditions the Linux kernel may reclaim memory, hit an allocation failure, or invoke the out-of-memory killer, and the memory.events counters described below tell these events apart.
The PID controller limits how many tasks a cgroup can create. According to the kernel's cgroup v2 reference, the controller counts kernel task IDs, threads included, so a process that spawns many threads can hit the task limit without starting many top-level programs. At that limit fork and clone fail with EAGAIN, and adding CPU time does not help.
Docker also says containers have no resource constraints by default, so we check the runtime configuration to see which limits apply.
CPU and memory settings leave disk I/O, network activity, and native GPU or browser work to their own controls.

- The enforcing kernel: on macOS, Docker Desktop runs Docker Engine inside a Linux VM, and container processes run under that VM's Linux kernel.
- CPU quota: once the container uses up its allowance, runnable work gets throttled until the next period.
- Memory hard limit: under different conditions the kernel may reclaim memory, hit an allocation failure, or invoke the out-of-memory killer.
- Task limit: at the limit fork and clone fail with EAGAIN, and adding CPU time does not help.
Inspect a limit without exhausting it
Inspecting a running container shows what limit it actually received, without triggering a failure. This command starts a throwaway Ubuntu container with all three limits and prints what its cgroup received:
docker run --rm --cpus 2 --memory 1g --memory-reservation 512m --memory-swap 1g --pids-limit 256 \
ubuntu:24.04 sh -c 'for f in cpu.max memory.max memory.low memory.high memory.swap.max pids.max; do
printf "%s: " "$f"; cat /sys/fs/cgroup/$f; done'On Docker 29.8.2 (OrbStack's Linux VM on an arm64 Mac), it printed:
cpu.max: 200000 100000
memory.max: 1073741824
memory.low: 536870912
memory.high: max
memory.swap.max: 0
pids.max: 256We read each line against the flag that set it.
cpu.max allows 200,000 microseconds of CPU time in every 100,000-microsecond period, which is two CPUs' worth.
memory.max is the 1 GiB hard limit in bytes.
memory.low is the 512 MiB reservation, which cgroup v2 treats as best-effort protection from reclaim, not as a ceiling.
memory.high stays at max, so nothing throttles the container below its hard limit.
memory.swap.max is 0 because --memory-swap equals --memory, which leaves the container no swap.
The same command without the flags printed max for the CPU quota, memory.max and pids.max, because a container gets no resource limits unless we set them.
With --pids-limit 8, a shell that started ten background jobs stopped with sh: 0: Cannot fork; that shell (dash) prints no error code, but the refused fork is the EAGAIN case.
Suppose a container has a CPU quota, a hard memory ceiling, and a task-count ceiling, and an agent starts a test runner in it.
Its workers consume CPU time, allocate memory, and try to create threads, each independently. Three cases follow:
- The workers stay inside the memory and task limits but burn through their CPU allowance, so throttling explains the slow progress.
- A new worker can't start because the PID ceiling is enforced, while the existing workers may still have memory to spare.
- A memory event shows up while the task count sits far below its ceiling.
Each case needs its own read instead of a single "container overload" label.
For the first, we compare cpu.max with how much CPU the runner needs.
For the second, we compare pids.current with pids.max and read the max counter in pids.events.
For the third, we read memory.events before and after the run.
We check how each container is configured, too.
The Compose service reference documents mem_limit and pids_limit, and says mem_limit must be consistent with deploy.resources.limits.memory.
When we set mem_limit: 1g next to a deploy memory limit of 512m, Docker Compose v5.5.0 refused the file with can't set distinct values on 'mem_limit' and 'deploy.resources.limits.memory'.
The Dev Container metadata reference lists runArgs among the image- and Dockerfile-specific properties.
A Compose-based devcontainer takes its limits from the Compose service instead, so limits set in runArgs have to be rewritten as Compose service settings when a config moves from an image to Compose.
Inspecting each resulting container and its cgroup shows what was applied without triggering a resource failure.
In cgroup v2, ancestors restrict their descendants: a child can't override a tighter parent limit, and siblings draw from a shared parent budget. Before estimating how much headroom a container has left, we look at the ancestor controls and shared consumption alongside its own values.
After setting per-container ceilings, we decide when containers can start, because several of them can start together and compete inside the same VM allocation. Admission control is a gate that decides whether a new job may start. One form is a queue in the agent runner that starts a fixed number of jobs at once, with that number picked from observed workload demand and VM and host headroom.
The sum of nominal container ceilings can't tell us whether the total is safe.

Figure text
Measure demand, set the VM allocation, and set container ceilings to bound each workload. Use admission to control how many jobs start, checking headroom before admitting a job. Watch it run and hold new starts when your chosen limit is reached.
- Check headroom before each start
- Measured level, under limit (fill)
- Held at the limit: job not started
- Admission check deciding (lamp)
- Ceilings bound each job. Admission decides how many start. This rule lives in the agent runner, and the thresholds are yours to set.
- 1 Measure, then set each container's ceilings
- 2 Set the VM's share, read what is left
- 3 Each job asks before it starts
- 4 Room, the job starts inside its ceilings
- 5 No room, the job is held
- 6 Revise from the readings
- Is there headroom?
- Started, bounded
- Agent runner
- What a job needs
- Admission check
- Held
- Container ceilings
- VM headroom
- Next job
- Linux VM
- Our chosen limit
- Tasks
- Processor time
- We review the readings and adjust the limits and the rule for starting jobs.
Sources: [1] Resource constraints | Docker Docs; [2] Control Group v2 - The Linux Kernel documentation; [3] Change your Docker Desktop settings | Docker Docs; [4] Define services in Docker Compose | Docker Docs.
Check events before diagnosing a failure
In the cgroup v2 memory controller, memory.events holds counters for different events:
highcounts the times tasks were throttled and pushed into reclaim after crossing thememory.highboundary, which Docker leaves atmax.maxcounts attempts to exceed the maximum boundary.oomcounts allocations that hit the limit and were about to fail, when the kernel would consider the OOM killer.oom_killcounts processes in the cgroup that an OOM killer actually killed.
These counters accumulate.
A nonzero value may predate the command we're investigating, so we note the starting value and the interval.
By default memory.events includes descendant events, while memory.events.local covers only the current cgroup, and the memory_localevents mount option changes whether memory.events includes descendants.
grep cgroup2 /proc/mounts lists the mount options; inside our test container it showed nsdelegate and no memory_localevents.
For PIDs, pids.events has a max counter for limit hits, and a separate mount option, pids_localevents, sets whether it covers the local cgroup or the subtree.
When we read a parent cgroup, that context keeps us from attributing a descendant's event to the wrong workload.
Exit status 137 can come from more than one cause.
Bash returns 128 + N for a process killed by fatal signal N, and the Linux signal reference gives SIGKILL the number 9.
A script can also literally exit 137 with nothing killed.
When we ran docker run ubuntu:24.04 sh -c 'exit 137', docker inspect reported ExitCode=137 and OOMKilled=false.
docker inspect -f '{{.State.OOMKilled}}' says whether a process in the container was killed for running out of memory since the container last started.
After confirming SIGKILL, we may still need to identify who sent it.
Before calling it an OOM incident, we match the test runner's log of which process exited against OOMKilled, memory.events and the kernel log.
| Symptom / candidate signal | Scope to capture | How to read it |
|---|---|---|
| Memory pressure | We compare before-and-after memory.events readings over the workload interval. We note the exact cgroup, whether events are local or include descendants, and the memory_localevents mount configuration, and we use memory.events.local for local attribution. Effective container and ancestor limits and shared ancestor consumption also matter. | Read high, max, oom and oom_kill by the meanings given above; a nonzero value alone does not identify the cause. |
| PID pressure | We compare before-and-after pids.events readings over the workload interval. We note the exact cgroup, whether events are local or cover the subtree, and the pids_localevents mount configuration, using pids.events.local where appropriate. We also read pids.current, pids.max, effective ancestor limits and shared ancestor consumption. | The PID controller counts tasks, including threads. Memory and CPU have separate accounting. |
| Host GPU / browser pressure | Host GPU and browser telemetry, for example a browser an agent drives on the Mac, which runs outside the VM entirely. | Read it from host tools; Linux cgroup counters do not show it. |
| Network-path pressure | Caller, endpoint, host / VM path and transport observations. | The CPU, memory and PID counters above do not cover network traffic; read the caller's and the endpoint's own logs for the same interval. |
Sources: Control Group v2 - The Linux Kernel documentation Resource constraints | Docker Docs Change your Docker Desktop settings | Docker Docs Define services in Docker Compose | Docker Docs Exit Status (Bash Reference Manual).
Match the control to the boundary
Each row names a concern, the boundary that controls it, and what to inspect there.
| Concern | Relevant boundary or control | What to inspect |
|---|---|---|
| One container consumes excessive CPU time | Container CPU quota or scheduling weight | Effective settings and throttling counters |
| One workload grows in memory | Container memory and swap controls | Effective limits, usage, and changes in scoped memory events |
| A workload creates too many tasks | Container PID controller | Task count, effective ceiling, and changes in PID limit hits |
| Several workloads compete at once | Admission policy and VM allocation | Concurrent jobs, VM allocation, and aggregate demand |
| Native applications lose host headroom | macOS host | Host memory and process telemetry over the same interval |
| A container reaches sensitive host files | Mount and privilege configuration | Source and destination paths, permissions, and effective access |
| A workload controls Docker | Daemon access | Which daemon is reachable and what authority it grants |
A read-only mount is an access control, not a resource limit, so it does not help with any of the pressure above. What a workload can do through daemon access is set by the daemon's authority, which may let it create other containers or add mounts. If a workload needs a separate kernel boundary, we look at the VM configuration as well as the container profile.
Where to start
When a job slows down or dies, start with its container's cpu.max, memory.events and pids.events.
If those stay quiet, check the VM allocation in your VM's resource settings (Docker Desktop or OrbStack), then the macOS host.
What an attacker targets here
The CPU, memory and tasks these limits cap are a target too: an attacker who cannot steal anything can still exhaust them.
- Expensive inputs: sponge examples raised energy consumption 10 to 200 times per request.
A container's
cpu.maxand memory limit bound only the work that runs inside it; The gateway as an attack surface covers limits on the request side. - Crafted files: PyTorch's
weights_onlyloader does not guard against denial of service, and a crafted manifest crashes an Ollama server under CVE-2025-1975. We load untrusted models in a container with no network and no mounted secrets, as Model files are code recommends, and readmemory.eventswhen one dies.