Secured VS Code Dev Containers for Coding Agents

Set up a hardened VS Code DevContainer that sandboxes coding agents while maintaining full development capability.

When to Use This Skill

• Setting up a new DevContainer for coding agent use
• Hardening an existing DevContainer against escape vectors
• Adding git worktree support for parallel development
• Setting up sibling Docker services (databases, emulators)
• Verifying security controls are working
• Setting up Node.js / pnpm in a DevContainer

Threat Model

We're protecting against three things:

1. Supply chain attacks - malicious npm packages executing code during install or at runtime
2. Prompt injection - malicious content convincing the agent to run harmful commands
3. Agent mistakes - unintentional destructive actions

The goal is to limit blast radius, not eliminate all risk.

Architecture Overview

┌─────────────────────────────────────────────────┐
│                  Host Machine                   │
│  ┌───────────────────────────────────────────┐  │
│  │              Docker Engine                │  │
│  │  ┌──────────────┐  ┌──────────────────┐   │  │
│  │  │ docker-proxy │◄─│  claude-code     │   │  │
│  │  │ (read-only)  │  │  (DevContainer)  │   │  │
│  │  └──────┬───────┘  └──────────────────┘   │  │
│  │         ▼                                 │  │
│  │  ┌──────────────┐                         │  │
│  │  │ Docker Socket│                         │  │
│  │  └──────────────┘                         │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

Security Controls Summary

Control	What It Blocks	How
Docker socket proxy	Container escape	Read-only API proxy (POST=0, EXEC=0)
No sudo	Privilege escalation	Not installed in image
Drop all capabilities	Kernel attack surface	cap_drop: [ALL] in docker-compose.yml
No new privileges	Setuid/setgid escalation	security_opt: no-new-privileges:true
No SSH keys	Git push / code exfil	Keys not mounted, agent socket deleted
VS Code IPC hardening	Host command execution	Three-layer env var + socket cleanup
No credential injection	Docker/git credential leaks	VS Code settings disabled

Documentation Index

Document	Contents
SECURITY-HARDENING.md	Three-layer defence against VS Code escape vectors, the .bashrc non-interactive shell subtlety
DOCKER-PROXY.md	Docker socket proxy setup, sibling container communication
NODE-SETUP.md	Node.js + pnpm Dockerfile patterns, startup commands
WORKTREE-SUPPORT.md	Git worktree support, dynamic container naming, isolated volumes
VERIFICATION.md	How to verify security controls, integration testing with devcontainers-cli, automated test scripts

Quick Start — Minimal Secured DevContainer

Three files are needed. See each sub-document for detailed explanations.

.devcontainer/devcontainer.json:

{
  "name": "Secured Dev Container",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/app",
  "remoteUser": "vscode",
  "shutdownAction": "stopCompose",
  "remoteEnv": {
    "SSH_AUTH_SOCK": "",
    "GPG_AGENT_INFO": "",
    "BROWSER": "",
    "VSCODE_IPC_HOOK_CLI": null,
    "VSCODE_GIT_IPC_HANDLE": null,
    "GIT_ASKPASS": null,
    "VSCODE_GIT_ASKPASS_MAIN": null,
    "VSCODE_GIT_ASKPASS_NODE": null,
    "VSCODE_GIT_ASKPASS_EXTRA_ARGS": null,
    "REMOTE_CONTAINERS_IPC": null,
    "REMOTE_CONTAINERS_SOCKETS": null,
    "REMOTE_CONTAINERS_DISPLAY_SOCK": null,
    "WAYLAND_DISPLAY": null
  },
  // postStartCommand: clean up sockets created before VS Code attaches
  "postStartCommand": "find /tmp -maxdepth 2 \\( -name 'vscode-ssh-auth-*.sock' -o -name 'vscode-remote-containers-ipc-*.sock' -o -name 'vscode-remote-containers-*.js' \\) -delete 2>/dev/null || true",
  // IPC socket cleanup (vscode-ipc-*.sock, vscode-git-*.sock) is handled by a background
  // loop in the Docker Compose command — postAttachCommand is unreliable for background
  // processes due to VS Code's cgroup-based lifecycle cleanup. See SECURITY-HARDENING.md.
  "customizations": {
    "vscode": {
      "settings": {
        "dev.containers.dockerCredentialHelper": false,
        "dev.containers.copyGitConfig": false
      }
    }
  }
}

.devcontainer/docker-compose.yml: See DOCKER-PROXY.md.

.devcontainer/Dockerfile: See NODE-SETUP.md or adapt for your language.

Accepted Risks

These are trade-offs for development usability:

Risk	Why Accepted
Network egress (data exfiltration)	Development requires internet access
Workspace write access	Essential for development; git tracks changes
Agent credentials readable	Token is revocable; limited blast radius
Environment variables (.env)	Development requires env vars, no production keys