Skip to content

feat(agent): add Docker sandbox backend for agent run - #42

Merged
radim10 merged 43 commits into
masterfrom
feat/docker-sandbox-backend
Sep 25, 2026
Merged

radim10 merged 43 commits into
masterfrom
feat/docker-sandbox-backend

Conversation

@radim10

@radim10 radim10 commented Sep 25, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds an opt-in Docker sandbox backend for agent run — a stronger alternative to the native Seatbelt/systemd-run/bubblewrap backend, running the agent inside an isolated container instead of a same-host sandboxed process.

Key properties:

  • Filesystem: allow-list, not deny-list — only the working directory is visible inside the container at all, instead of specific paths being blocked while everything else stays reachable.
  • Network: enforced by a real firewall inside the container's own network namespace (a short-lived privileged holder container installs iptables default-DROP rules, then verifies they actually took effect before trusting them), not by the agent choosing to honor HTTPS_PROXY/HTTP_PROXY. Verified this holds under a real adversarial bypass attempt (raw socket to an arbitrary host, and an attempt to flush the firewall from inside the agent container — both fail as designed). DNS gets no exception at all, closing a data-exfiltration channel that no per-container firewall rule could otherwise block (Docker's embedded resolver forwards unresolved lookups via the host's own DNS stack, outside the container's network namespace entirely).
  • Capabilities: agent container runs with --cap-drop ALL, no-new-privileges, --init (proper zombie reaping/signal handling), and a --pids-limit (fork-bomb containment) — always on, no configuration needed.
  • Cross-platform: works on macOS, Linux, and Windows (via Docker Desktop), handling each platform's different container-to-host networking model.

Configurability:

  • [sandbox] image / dockerfile — run a custom image or build one from a project-supplied Dockerfile, for anything beyond the maintained default (Claude Code + Codex pre-installed, plus common tooling including Python). None of the sandbox constraints above can be loosened by a custom image.
  • [sandbox] memory / cpus — optional resource caps (opt-in, no default, since an automatic cap could silently break a legitimate heavy task).
  • Matching CLI overrides for a single invocation: --docker-sandbox, --docker-image, --docker-dockerfile, --docker-memory, --docker-cpus.
  • New agent docker command group: build, status, cleanup (finds and removes leftover containers/networks from a crashed run — every resource is named after its own session id, so it's traceable), doctor (readiness check without starting a real sandboxed run).

Also included:

  • Git identity forwarding, persistent login/config across runs (shared named volume), Codex device-code login support (normal OAuth can't work from an isolated container).
  • agent validate now checks Docker readiness instead of native-backend mechanisms for a Docker-backend profile, so it doesn't falsely report Windows as unsupported for a profile that doesn't need the native backend at all.

Testing

  • 308 tests, run and passing on macOS, Linux (native, via a real container — not just cross-compiled), and Windows CI.
  • Docker-gated integration tests exercise the firewall (self-verification, DNS blocking, proxy-only egress), container resource limits, and image lifecycle against a real Docker daemon; they skip cleanly when Docker isn't available.
  • Extensively verified by hand against real Docker throughout development: full agent sessions with Claude Code and Codex, credential injection through the sandboxed network path, custom images/Dockerfiles, resource limits, and crash-cleanup scenarios.

Known limitations

  • No CPU/memory cap by default (opt-in only, by design).
  • A pre-existing, unrelated Windows path-separator bug in directory-profile loading was fixed along the way (config.rs) since it was blocking this branch's CI, but it isn't part of the Docker sandboxing feature itself.

radim10 and others added 30 commits September 23, 2026 09:25
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…fficial native installers, ensuring proper permissions and symlink setup for non-root users
…ERM and COLORTERM environment variables for improved terminal capabilities
…sandbox profile, enforcing mutual exclusivity and validation checks
…es to include necessary OAuth and authentication endpoints
…box, detailing custom image support, network egress enforcement, and command overrides
…res, including network isolation, filesystem access, and custom image support
…ner handling and reduced curl timeout for firewall verification
…on and network setup to enhance clarity during startup
… including cleanup of leftover networks and containers
…pport loading profiles from global, directory, or auto-detected sources
…ent commands, detailing session tracing and network handling
…and pip support, enabling package installation and isolated environments
…stallation in the default Docker image, clarifying package management capabilities in the sandbox environment
…verifying CLI availability, daemon reachability, and image status
…nsuring accurate validation and reporting for Docker backend environments
…r enhanced security and consistency across platforms
…llowing users to specify memory and CPU allocations for enhanced control over resource usage
…sing --init and setting a pids-limit of 2048
…reads in Docker sandbox to avoid character device confusion
…box to prevent root ownership of mounted files on Linux
@radim10 radim10 self-assigned this Sep 25, 2026
@radim10 radim10 changed the title Feat/docker sandbox backend feat(agent): add opt-in Docker sandbox backend for agent run Sep 25, 2026
@radim10 radim10 changed the title feat(agent): add opt-in Docker sandbox backend for agent run feat(agent): add Docker sandbox backend for agent run Sep 25, 2026
@radim10
radim10 merged commit 4304a7c into master Sep 25, 2026
3 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