Agent Containment Strategies

agent-containment-guide.md

AI Agent Containment: Choosing Between Dev Containers, Leash, and Container Use

1. Use-Case Heuristics

Scenario A: CLI agents + outbound network required (inference, MCP, web)

Choose: Leash

• Rationale: Container alone cannot prevent exfiltration or tool misuse when network is open. Leash adds policy enforcement (Cedar), MCP authorization/monitoring, and runtime observability—the control layer you actually need.
• Trade-off: Additional tooling complexity; depends on StrongDM/Leash maturity and Cedar policy learning curve.

Scenario B: CLI agents + filesystem/process isolation only (no network)

Choose: Dev Containers or simple Docker image

• Rationale: Container boundaries are sufficient when agents cannot reach the network. Use devcontainers if you want a standard env spec reusable across tooling; use plain Docker/Leash if you just need a one-command "launch agent in sandbox" UX.
• Trade-off: Minimal governance overhead; but remember isolation is only as strong as your mounts and forwarded credentials.

Scenario C: Interactive development + agents (humans + agents in same env)

Choose: Dev Containers

• Rationale: Standard, widely-supported format for reproducible dev environments; integrates tightly with VS Code/editors; reusable across CI/local/cloud.
• Trade-off: Devcontainers are not optimized for agent governance; treat agents as ordinary CLIs inside the env and add policy layers separately if needed.

Scenario D: Parallel agent execution + disposability (run many agents, discard failures cleanly)

Choose: Container Use

• Rationale: Explicit per-agent fresh container + git branch/worktree isolation; audit happens via git review; failures don't contaminate shared state.
• Trade-off: Commits you to a worktree-per-agent workflow and MCP-mediated tool access; limits flexibility if you have a custom branching strategy or want "agent as direct process inside container."

---

2. Tool Comparison Matrix

Aspect	Dev Containers	Leash	Container Use
Primary UX	Editor-centric (Reopen in Container); CLI exists (devcontainer open)	leash run <agent> command; wraps agents with policy/telemetry	MCP server (container-use stdio); agent talks to tool over MCP
Containment	Container FS/process isolation; no policy layer	Container + Cedar policy enforcement + MCP auth/monitoring	Fresh container per agent + git worktree per agent
Network governance	None (basic Docker network isolation); relies on layer config	Built-in (Cedar policies, MCP authorization hooks, monitoring)	None (relies on Container Use's config); agent accesses tools via MCP
Extensibility	.devcontainer/ config; reusable across tooling	Extend Dockerfile.coder or bring custom image; Cedar policies	Dagger-defined environment + MCP tool interface
Governance/audit	Manual (logs + mounts + credential discipline)	Automated (policy violations logged/blocked; action auditing)	Git-mediated (agent changes reviewed via branch/worktree)
Credential isolation	Manual (avoid mounting home; forward selectively)	Can restrict credential access per agent/policy	Manual (agent accesses creds via MCP tools you expose)
Multi-agent parallel	No built-in support	Yes (via Leash's sandbox manager)	Yes (via Container Use's worktree strategy)
Opinionated workflow	No (you choose env spec + how to use it)	Moderate (agent-focused; Cedar policies define boundaries)	High (enforces per-agent worktree + branch isolation)

---

3. Decision Tree + Setup Patterns

Q1: Do agents need outbound network?

• No → Go to Q2A
• Yes → Go to Q2B

Q2A: (No network required)

• Do you want a reproducible dev env spec reusable across tooling?
  • Yes → Use Dev Containers (define tooling in .devcontainer/ or Dockerfile; launch agents as CLIs inside the env)
  • No → Use simple Docker image or Leash without policy rules (sandbox for containment only, not governance)

Q2B: (Network required: inference, MCP, web)

• Do you need observable/enforceable policy (e.g., "block unknown MCP servers," "audit every tool call")?
  • Yes → Use Leash (policy enforcement + monitoring + MCP authorization)
  • No → Use Dev Containers + manual credential/network discipline (container boundaries + narrow mounts + short-lived tokens)

---

Setup Pattern: Leash + Your Toolchain

If you choose Leash (recommended for your scenario: CLI agents + outbound network + risk mitigation):

1. Define environment in Dockerfile (extends Leash's Dockerfile.coder or from scratch):

   • Install OS-level deps via apt/brew
   • Install mise for language/tool versioning
   • (Optional) commit .devcontainer/ as parallel canonical spec; Leash can mirror or consume it

2. Configure mise inside container:

   • Put mise.toml in repo; Leash container installs via mise install
   • Persist mise data via Docker volume: --mount-mise-data or explicit bind to preserve builds across rebuilds

3. Manage credentials explicitly:

   • No ambient SSH agent forwarding; pass tokens as short-lived env vars
   • No mounting of $HOME; apply dotfiles selectively via postCreateCommand or Dockerfile

4. Define Cedar policies (Leash-specific):

   • Allow specific MCP servers (allowlist, not allowall)
   • Restrict network to known hosts (inference providers, specific APIs)
   • Audit/log all tool invocations

5. Launch:

   • leash run --image <your-image> -- <agent-cli> <agent-args>
   • Policies are enforced; telemetry is collected; failures are sandboxed

---

Setup Pattern: Dev Containers (if you choose them)

If you choose Dev Containers (no network required, or you're OK with manual discipline):

1. Create .devcontainer/devcontainer.json with:

   • Base image or Dockerfile
   • Features for language runtimes (Node, Rust)
   • postCreateCommand: mise install && yarn install && git clone <dotfiles-repo> && apply-dotfiles

2. Persist versioning:

   • Use mise.toml or mise.lock for tool versions
   • Volume-mount mise data if rebuilds are frequent: "mounts": ["type=volume,source=mise-data,target=/home/vscode/.local/share/mise"]

3. Launch agents:

   • Open repo in container (VS Code or devcontainer open)
   • Run agent CLIs from integrated terminal (they're inside the container)

4. Discipline:

   • Avoid mounting home directory; mount repo only (read-write) + any external APIs (read-only)
   • Restrict credentials: forward only what the agent needs for that task
   • Monitor container logs manually or via Docker observability

---

Appendix: Key Research Findings

• MCP security: Dynamic tool discovery and over-permissioning are known risks; MCP security literature recommends allowlist policies and client-side authorization enforcement. Leash's MCP authorization/monitoring is a direct response to this.
• Filesystem isolation alone is insufficient: Once an agent has network access, the perimeter shifts to "what it can reach" (APIs, MCP servers, credentials), not just "what files it can touch."
• Credential isolation is the highest-leverage control: Even inside a container, if an agent can access your SSH keys, AWS tokens, or GitHub PATs, it can cause damage outside the container.
• Dev Containers are a standard, not a full sandbox: Widely supported, good for reproducibility, but assume you're adding discipline (mounts, credentials, network) on top.
• Container Use is opinionated on workflow: Per-agent worktrees are powerful for parallelism and reviewability but don't fit all branching strategies.
• Leash is optimized for agent governance: Policy enforcement + observability directly address "permissive agents + outbound network" scenarios.