Skip to content

Linux sandbox with cgroup support [ignoring sandbox in MacOS]#5

Merged
HackStrix merged 7 commits intomainfrom
feature/sandbox-template
Mar 10, 2026
Merged

Linux sandbox with cgroup support [ignoring sandbox in MacOS]#5
HackStrix merged 7 commits intomainfrom
feature/sandbox-template

Conversation

@HackStrix
Copy link
Owner

@HackStrix HackStrix commented Mar 10, 2026

This pull request introduces cgroup v2 resource isolation support for worker processes, along with comprehensive tests and CI integration. The main changes include adding cgroup configuration options to the ProcessFactory, implementing sandbox resource management, and providing both unit and integration tests to verify kernel-level enforcement. The CI pipeline and Docker setup are also updated to support these features.

Cgroup resource isolation and sandboxing:

  • Added new fields to ProcessFactory (cgroupMemory, cgroupCPU, cgroupPIDs, enableSandbox) and corresponding builder methods (WithMemoryLimit, WithCPULimit, WithPIDsLimit, WithInsecureSandbox) to allow per-worker cgroup resource limits. These values are passed to the sandbox layer when spawning workers. (process_worker_factory.go [1] [2] [3] [4] [5] [6]
  • Introduced the sandboxConfig struct and sandboxHandle interface to abstract resource constraints and lifecycle management for sandboxes. (sandbox.go sandbox.goR1-R16)
  • Ensured cgroup resources are cleaned up when a worker process exits. (process_worker_factory.go [1] [2]

Testing improvements:

  • Added unit tests for cgroup configuration builder methods to ensure correct option validation and chaining. (factory_cgroup_test.go factory_cgroup_test.goR1-R137)
  • Added integration tests (Linux-only) to verify that worker processes are placed in the correct cgroup, that cgroup directories are created and cleaned up, and that kernel-level limits are enforced for PIDs and memory. (sandbox_integration_test.go sandbox_integration_test.goR1-R242)

CI and build updates:

  • Updated the minimum Go version to 1.22 in go.mod and all workflow jobs, removing 1.21.x from the matrix due to new requirements. (go.mod [1] .github/workflows/ci.yml [2] [3]
  • Added a dedicated CI job for cgroup integration tests, running only on the latest Go version and verifying cgroupv2 availability. (.github/workflows/ci.yml .github/workflows/ci.ymlR39-R74)

Docker and Compose enhancements:

  • Added a Dockerfile that builds the playwright example with Go and sets up Playwright with Chromium in a multi-stage build. (Dockerfile DockerfileR1-R24)
  • Added a simple docker-compose.yaml for the Playwright service. (docker-compose.yaml docker-compose.yamlR1-R5)

@HackStrix HackStrix force-pushed the feature/sandbox-template branch from 2d26098 to d69c759 Compare March 10, 2026 06:49
- Layer 1 (sandbox_linux_test.go): unit tests for applySandboxFlags and cgroupHandle
  using temp cgroup root (activeCgroupRoot injection) — no real cgroup privileges needed

- Layer 2 (factory_cgroup_test.go): unit tests for ProcessFactory builder methods
  (WithMemoryLimit, WithCPULimit, WithPIDsLimit) — runs on all platforms

- Layer 3 (sandbox_integration_test.go): integration tests spawning real processes
  to verify born-in-cgroup, directory lifecycle, and limit file enforcement
  (gated with HERD_CGROUP_TEST=1, requires root/cgroup delegation on Linux)

- testdata/healthworker/main.go: minimal HTTP server for integration test spawning

- sandbox.go: shared types (sandboxConfig, sandboxHandle) used by all sandbox impls
Add activeCgroupRoot package variable (defaults to herdCgroupRoot) so tests can
redirect all cgroup operations to a temp directory without requiring real cgroup
privileges. All references to herdCgroupRoot in applySandboxFlags now use
activeCgroupRoot, enabling fast unit tests via t.TempDir() redirection.
- Drop 1.21.x from test matrix (incompatible with go.mod requirement of >= 1.22)
- Add new cgroup-integration job: detects cgroupv2 availability, builds testdata,
  and runs Layer 3 integration tests as root with HERD_CGROUP_TEST=1 gate
- Existing test job in matrix covers Layer 1 (Linux-only unit tests) and Layer 2
  (portable factory tests) automatically via normal go test
…r startup

The previous limit of 5 PIDs was too tight for a Go HTTP server to start, causing
pthread_create to fail. This demonstrates the limit works, but isn't a realistic test.

Changed to 30 PIDs which allows the healthworker to start while still verifying
that the pids.max cgroup file is written and enforced at the kernel level.
Also added logging to show actual pids.current usage.
@HackStrix HackStrix changed the title Scaffold macOS/Linux sandbox support template Scaffold macOS/Linux sandbox support template with cgroup support Mar 10, 2026
@HackStrix HackStrix changed the title Scaffold macOS/Linux sandbox support template with cgroup support Linux sandbox with cgroup support [ignoring sandbox in MacOS] Mar 10, 2026
@HackStrix HackStrix merged commit 120faaf into main Mar 10, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant