<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-11-1-docker-sandboxed-agent-execution/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-11-1-docker-sandboxed-agent-execution/</id>
  <title>Docker-Sandboxed Agent Execution</title>
  <updated>2026-02-11T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-11-1-docker-sandboxed-agent-execution/"/>
  <summary>Proposes running agents inside containers with memory, CPU, and process limits so a runaway agent cannot take the orchestrator or the host machine down with it.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec Kitty’s current orchestrator runs AI agents directly on the host system without resource limits. This creates safety risks for autonomous agent execution:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Memory exhaustion&lt;/strong&gt;: Runaway agents can consume all available RAM, crashing the orchestrator or system&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CPU starvation&lt;/strong&gt;: Infinite loops or compute-intensive operations can monopolize CPU&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fork bombs&lt;/strong&gt;: Agents can spawn unlimited child processes, exhausting PID limits&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;File system access&lt;/strong&gt;: Agents have unrestricted access to host file system beyond intended working directory&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Network access&lt;/strong&gt;: Agents can make arbitrary network requests without controls&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Competitive analysis of Swarm (mtomcal/swarm) demonstrates that Docker sandboxing with memory/CPU/PID limits is an effective safety pattern for parallel AI agent execution. As Spec Kitty moves toward autonomous multi-agent orchestration (Feature 013: cross-repo convergence), these safety concerns become critical.&lt;/p&gt;
&lt;p&gt;Additionally, Entire.io (Tier 1 competitive threat) is building multi-agent orchestration. If they adopt similar safety patterns before Spec Kitty, it creates a perception gap on production-readiness.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Safety&lt;/strong&gt;: Prevent runaway agents from affecting system stability&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Isolation&lt;/strong&gt;: Ensure agents cannot access unintended resources (files, network, processes)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reproducibility&lt;/strong&gt;: Provide consistent execution environment across different systems&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Industry standard&lt;/strong&gt;: Docker is ubiquitous, well-understood, well-tested&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Operational experience&lt;/strong&gt;: Swarm’s production use validates this approach&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Production scale validation&lt;/strong&gt;: Cursor research demonstrates lock-based coordination fails at scale (“20 agents slow to 2-3 throughput”); isolation via containers enables hundreds of concurrent agents&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Competitive parity&lt;/strong&gt;: Match or exceed Entire.io’s agent safety capabilities&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;User trust&lt;/strong&gt;: Demonstrate production-grade safety for enterprise adoption&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Debugging&lt;/strong&gt;: Opt-out capability for local debugging without overhead&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1&lt;/strong&gt;: Docker containers with resource limits (chosen)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2&lt;/strong&gt;: Linux cgroups directly (no container)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3&lt;/strong&gt;: No sandboxing (current state)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4&lt;/strong&gt;: VM-based isolation&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Docker containers with resource limits”, because:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Industry standard&lt;/strong&gt;: Docker is ubiquitous in software development, well-understood by engineers&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Proven pattern&lt;/strong&gt;: Swarm’s production use with 235 commits validates effectiveness&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Comprehensive isolation&lt;/strong&gt;: Memory, CPU, PID, network, file system all controlled&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Minimal changes&lt;/strong&gt;: Orchestrator modifications are localized to &lt;code dir=&quot;auto&quot;&gt;executor.py&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Debugging flexibility&lt;/strong&gt;: Opt-out flag (&lt;code dir=&quot;auto&quot;&gt;--no-sandbox&lt;/code&gt;) allows local debugging&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Enterprise credibility&lt;/strong&gt;: Demonstrates production-grade safety for enterprise sales&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Safety&lt;/strong&gt;: Prevents OOM crashes, CPU starvation, fork bombs from affecting orchestrator or system&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Isolation&lt;/strong&gt;: Agents cannot access host file system beyond mounted working directory&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reproducibility&lt;/strong&gt;: Same Docker image ensures consistent environment across developer machines, CI, production&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Resource monitoring&lt;/strong&gt;: Docker stats provide real-time visibility into agent resource usage&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Security&lt;/strong&gt;: Container security options (&lt;code dir=&quot;auto&quot;&gt;--no-new-privileges&lt;/code&gt;) prevent privilege escalation&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Trust&lt;/strong&gt;: Enterprise customers see production-grade safety (compliance, governance requirement)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Competitive parity&lt;/strong&gt;: Matches Swarm’s safety model, exceeds Entire.io (which has no sandboxing currently)&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Overhead&lt;/strong&gt;: Container spawn time adds ~1-2 seconds per agent (vs direct spawn)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Complexity&lt;/strong&gt;: Requires Docker installed on all systems (developer machines, CI, production)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Disk space&lt;/strong&gt;: Docker images consume disk space (~500MB for base Python image)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Network complexity&lt;/strong&gt;: Container networking adds layer of indirection for debugging&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Learning curve&lt;/strong&gt;: Developers unfamiliar with Docker need to learn container concepts&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Opt-out available&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;--no-sandbox&lt;/code&gt; flag allows running agents on host for debugging (trade-off: safety vs speed)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Image maintenance&lt;/strong&gt;: Requires maintaining &lt;code dir=&quot;auto&quot;&gt;Dockerfile.agent-sandbox&lt;/code&gt; (but this is standard DevOps practice)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Configuration surface&lt;/strong&gt;: Docker config (memory_limit, cpu_limit, etc.) adds configuration options to manage&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Success Metrics&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Performance&lt;/strong&gt;: Container overhead &amp;#x3C;10% (measured: agent spawn time, execution time)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reliability&lt;/strong&gt;: Zero OOM crashes from runaway agents in production (vs current state: occasional crashes)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Adoption&lt;/strong&gt;: 95%+ of agent executions use sandboxed mode (opt-out rare, only for debugging)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Operational&lt;/strong&gt;: Docker image build/deploy works in CI/CD pipeline&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Validation Timeline&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Week 1-2&lt;/strong&gt;: Implementation + unit tests&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Week 3-4&lt;/strong&gt;: Integration testing with real WP executions&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Week 5-6&lt;/strong&gt;: Production rollout (sandboxed as default)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Month 2-3&lt;/strong&gt;: Monitor metrics, adjust limits if needed&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Confidence Level&lt;/strong&gt;: &lt;strong&gt;HIGH&lt;/strong&gt; (9/10)&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Validated by Swarm’s production use&lt;/li&gt;
&lt;li&gt;Docker is proven, stable technology&lt;/li&gt;
&lt;li&gt;Minimal risk, clear rollback path (opt-out flag)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;docker-containers-chosen&quot;&gt;Docker Containers (Chosen)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Description&lt;/strong&gt;: Run agents in Docker containers with &lt;code dir=&quot;auto&quot;&gt;--memory&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--cpus&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--pids-limit&lt;/code&gt; flags.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Industry standard solution (Docker ubiquitous)&lt;/li&gt;
&lt;li&gt;Comprehensive isolation (memory, CPU, PID, network, file system)&lt;/li&gt;
&lt;li&gt;Proven by Swarm’s production use (235 commits, battle-tested)&lt;/li&gt;
&lt;li&gt;Minimal code changes (localized to executor.py)&lt;/li&gt;
&lt;li&gt;Real-time monitoring via &lt;code dir=&quot;auto&quot;&gt;docker stats&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Security hardening options (&lt;code dir=&quot;auto&quot;&gt;--no-new-privileges&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;--security-opt&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Debugging flexibility (opt-out flag available)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires Docker installed (dependency)&lt;/li&gt;
&lt;li&gt;Container spawn overhead (~1-2 seconds)&lt;/li&gt;
&lt;li&gt;Docker image storage (~500MB)&lt;/li&gt;
&lt;li&gt;Container networking complexity&lt;/li&gt;
&lt;li&gt;Learning curve for Docker-unfamiliar developers&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;linux-cgroups-directly&quot;&gt;Linux cgroups Directly&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Description&lt;/strong&gt;: Use Linux cgroups v2 API to set resource limits without containers.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No Docker dependency (lower barrier to entry)&lt;/li&gt;
&lt;li&gt;Slightly faster (no container overhead)&lt;/li&gt;
&lt;li&gt;More direct control over resource limits&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Linux-only (not portable to macOS for local development)&lt;/li&gt;
&lt;li&gt;More complex implementation (cgroups API is lower-level than Docker CLI)&lt;/li&gt;
&lt;li&gt;No file system isolation (agents still access host file system)&lt;/li&gt;
&lt;li&gt;No network isolation&lt;/li&gt;
&lt;li&gt;Less familiar to developers (Docker is more common)&lt;/li&gt;
&lt;li&gt;No standard image management (harder to ensure consistent environment)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;no-sandboxing-current-state&quot;&gt;No Sandboxing (Current State)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Description&lt;/strong&gt;: Continue running agents directly on host without resource limits.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Zero overhead (fastest possible execution)&lt;/li&gt;
&lt;li&gt;Simplest implementation (no changes needed)&lt;/li&gt;
&lt;li&gt;No dependencies (works everywhere Python works)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Unsafe&lt;/strong&gt;: Runaway agents can crash orchestrator or system&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No isolation&lt;/strong&gt;: Agents can access any file on host&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No resource limits&lt;/strong&gt;: Agents can consume unlimited memory, CPU&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Not production-ready&lt;/strong&gt;: Enterprise customers will question safety&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Competitive risk&lt;/strong&gt;: Perception gap vs competitors with sandboxing&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;vm-based-isolation&quot;&gt;VM-Based Isolation&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Description&lt;/strong&gt;: Run agents in lightweight VMs (e.g., Firecracker, gVisor).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Strongest isolation (kernel-level separation)&lt;/li&gt;
&lt;li&gt;Security benefits (VM escape harder than container escape)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Too heavy&lt;/strong&gt;: VM startup time 5-10 seconds (vs 1-2 seconds for containers)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Complex&lt;/strong&gt;: VM management much more complex than Docker&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Resource intensive&lt;/strong&gt;: VMs consume more memory than containers&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Overkill&lt;/strong&gt;: Agent code is not malicious, just potentially buggy; VM-level isolation unnecessary&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Less familiar&lt;/strong&gt;: Firecracker/gVisor less common than Docker&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;References&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Swarm architecture analysis: &lt;code dir=&quot;auto&quot;&gt;spec-kitty-planning/competitive/tier-1-threats/entire-io/SWARM-COMPARISON.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Swarm codebase: &lt;a href=&quot;https://github.com/mtomcal/swarm&quot;&gt;https://github.com/mtomcal/swarm&lt;/a&gt; (see Docker sandbox implementation)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cursor scaling research&lt;/strong&gt;: &lt;a href=&quot;https://cursor.com/blog/scaling-agents&quot;&gt;https://cursor.com/blog/scaling-agents&lt;/a&gt;
&lt;ul&gt;
&lt;li&gt;Key finding: Lock-based coordination creates severe bottlenecks (20 agents → 2-3 effective throughput)&lt;/li&gt;
&lt;li&gt;Validation: Hundreds of concurrent workers require process isolation (not locks)&lt;/li&gt;
&lt;li&gt;Conclusion: Isolation via containers enables scale; locking prevents it&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;Product requirements: &lt;code dir=&quot;auto&quot;&gt;spec-kitty-planning/product-ideas/prd-agent-orchestration-integration-v1.md&lt;/code&gt; (AD-001)&lt;/li&gt;
&lt;li&gt;Integration spec: &lt;code dir=&quot;auto&quot;&gt;spec-kitty-planning/competitive/tier-1-threats/entire-io/INTEGRATION-SPEC.md&lt;/code&gt; (Section 2.1)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Implementation Files&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;orchestrator/executor.py&lt;/code&gt; - Add &lt;code dir=&quot;auto&quot;&gt;spawn_agent_sandboxed()&lt;/code&gt; method&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;orchestrator/config.py&lt;/code&gt; - Add &lt;code dir=&quot;auto&quot;&gt;DockerSandboxConfig&lt;/code&gt; class&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;docker/Dockerfile.agent-sandbox&lt;/code&gt; - Base image for agent execution&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Related ADRs&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;ADR-2026-02-11-2: Fresh Context Execution Mode (complementary safety pattern)&lt;/li&gt;
&lt;li&gt;ADR-2026-01-23-6: Config-Driven Agent Management (agent configuration foundation)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Rollback Plan&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;If Docker overhead unacceptable: Use &lt;code dir=&quot;auto&quot;&gt;--no-sandbox&lt;/code&gt; flag globally (environment variable)&lt;/li&gt;
&lt;li&gt;If Docker unavailable on system: Automatic fallback to direct spawn (with warning)&lt;/li&gt;
&lt;li&gt;Configuration: &lt;code dir=&quot;auto&quot;&gt;docker_sandbox.enabled = false&lt;/code&gt; in config/docker_sandbox.yaml&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
