Skip to content

Devcontainers

IDE-native isolation that makes sandboxing transparent to both developers and agents. The agent operates inside a container but sees a normal development environment.

Devcontainers for Agents

Devcontainers reduce sandboxing friction:

  • VS Code, JetBrains, and other editors connect natively
  • Agents see a full environment without knowing they're sandboxed
  • Config travels with the repo in .devcontainer/
  • Same setup everywhere: local machines, CI, agent runs

The agent doesn't need special sandbox awareness. It works in an environment that happens to be isolated.

Architecture

┌─────────────────────────────────────┐
│           Host Machine               │
│  ┌───────────────────────────────┐  │
│  │      Docker Container          │  │
│  │  ┌─────────────────────────┐  │  │
│  │  │   Dev Environment        │  │  │
│  │  │   - Language runtimes    │  │  │
│  │  │   - Dependencies         │  │  │
│  │  │   - Tools                │  │  │
│  │  └─────────────────────────┘  │  │
│  │         ↑                      │  │
│  │    Project mount               │  │
│  └───────────────────────────────┘  │
│         ↑                            │
│    VS Code Remote                    │
└─────────────────────────────────────┘
  1. Docker container runs with a development environment
  2. VS Code connects via Remote Containers extension
  3. Project directory mounts into the container
  4. Agent operates inside the container, seeing isolated filesystem
  5. Network, process, and resource limits apply transparently

Configuration

A minimal .devcontainer/devcontainer.json:

{
  "name": "Project Dev",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/python:1": {}
  }
}

For agent isolation, add restrictions:

{
  "name": "Sandboxed Agent",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "runArgs": [
    "--network=none",
    "--memory=4g",
    "--cpus=2"
  ],
  "mounts": [
    "source=${localWorkspaceFolder},target=/workspace,type=bind"
  ]
}

The container has no network access (--network=none), 4GB memory and 2 CPU cores, with only the project directory mounted.

Integration with Agent Runtimes

Claude Code and similar agents work inside devcontainers without modification:

# Start devcontainer
devcontainer up --workspace-folder .

# Run agent inside
devcontainer exec --workspace-folder . claude

The agent sees /workspace as its filesystem root, with no visibility into host directories.

Limitations

Devcontainers aren't production sandboxes:

Limitation Impact
Docker required Desktop overhead, licensing considerations
Shared kernel Container escapes are documented vulnerabilities
Networking complexity Allowing specific hosts requires extra configuration
Startup time Initial container build can be slow

For development with trusted codebases, these tradeoffs are fine. For untrusted code at scale, stronger isolation is needed.

Use Cases

Good fit: Local development with AI agents, team environments needing reproducibility, projects already using devcontainers, and trusted internal codebases.

Poor fit: Running AI-generated code from unknown sources, multi-tenant platforms, environments requiring kernel-level isolation, or compliance regimes demanding VM separation.

External Resources