cgroups

cgroups v2 enforce per-agent resource limits declared in spec.resources. Limits are applied at spawn time by the PlatformEnforcer.

Supported Limits

Manifest Field	cgroup Controller	Description
`memory_limit`	`memory.max`	Maximum resident memory (e.g. `512Mi`, `2Gi`)
`cpu_shares`	`cpu.weight`	Relative CPU weight (maps to cgroups v2 `cpu.weight`)
`max_open_files`	`pids.max` + `rlimit`	File descriptor limit (also applied via `setrlimit`)

Manifest Declaration

spec:
  resources:
    memory_limit: 512Mi
    cpu_shares: 100
    max_open_files: 64

cgroup Hierarchy

Each agent gets its own cgroup under agentd's cgroup subtree:

/sys/fs/cgroup/
  scarab-runtime/
    agentd/
      agent-<uuid>/
        memory.max
        cpu.weight
        pids.max

Memory Enforcement

When an agent's resident memory exceeds memory_limit, the kernel OOM killer terminates the agent process. This generates an audit entry and may trigger the anomaly detector.

CPU Fairness

cpu_shares (mapped to cpu.weight) is a relative weight. An agent with cpu_shares: 200 gets twice as much CPU time as one with cpu_shares: 100 when both are runnable.

Default cpu.weight is 100 (the cgroup v2 default).

Validation

# Run cgroup enforcement tests (requires root + cgroups v2 enabled)
sudo cargo test cgroups

Tests verify that cgroup limits are created correctly and enforce at the kernel level.

Checking Limits

To inspect a running agent's cgroup:

# Find the cgroup path
cat /proc/$(pgrep -f "agent-binary")/cgroup

# Check limits
cat /sys/fs/cgroup/scarab-runtime/agentd/agent-<uuid>/memory.max
cat /sys/fs/cgroup/scarab-runtime/agentd/agent-<uuid>/cpu.weight

Scarab-Runtime Documentation