devcontainer-setup

name	devcontainer-setup
description	Templates and process for creating devcontainer configurations. Use this when setting up a new project, adding devcontainer support, or creating devcontainers for worktrees.

Every project must have a devcontainer. Agents execute all commands inside devcontainers — never on the host.

Devcontainer Tiers

Yolo (Developer Agent) — Safelisted Network

For sandboxed development. The agent limits network access to safelisted registries (Terraform, PyPI, Azure/Jira/GitLab docs) per its agent instructions. No ad-hoc package installation at runtime.

// .devcontainer/devcontainer.json
{
  "name": "${project-name}-yolo",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    // Add only what the project needs
  },
  "postCreateCommand": "echo 'Yolo devcontainer ready'",
  "customizations": {
    "vscode": {
      "extensions": ["GitHub.copilot"]
    }
  }
}

Interactive — With Network

For agents that need human-approved network access (Architect, Product, Designer, Orchestrator).

// .devcontainer/devcontainer.json
{
  "name": "${project-name}",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    // Add only what the project needs
  },
  "postCreateCommand": "echo 'Interactive devcontainer ready'",
  "customizations": {
    "vscode": {
      "extensions": ["GitHub.copilot"]
    }
  }
}

Language Features

Add only what the project requires:

// TypeScript
"ghcr.io/devcontainers/features/node:1": {}

// Python (with uv)
"ghcr.io/devcontainers/features/python:1": {}

// Rust
"ghcr.io/devcontainers/features/rust:1": {}

// C/C++
"ghcr.io/devcontainers/features/common-utils:1": {}
// Install build tools via postCreateCommand:
// "postCreateCommand": "apt-get update && apt-get install -y build-essential clang clang-format clang-tidy cppcheck"

// Go
"ghcr.io/devcontainers/features/go:1": {}

ARM64 (Apple Silicon) Notes

• mcr.microsoft.com/devcontainers/universal:2 does NOT support ARM64.
• Use mcr.microsoft.com/devcontainers/base:ubuntu instead.
• All ghcr.io/devcontainers/features/* features support ARM64.

Pre-flight Check

See .github/instructions/devcontainer.instructions.md for context detection and command rules before running any dev command.

Setup Process

New Project

1. Create .devcontainer/devcontainer.json with the appropriate tier template.
2. Add language features needed for the project.
3. Test: devcontainer up --workspace-folder .
4. Verify: devcontainer exec --workspace-folder . <build-command>

Worktree Task

1. Create worktree: git worktree add ../worktrees/<branch> -b <branch>
2. Start container: devcontainer up --workspace-folder ../worktrees/<branch>
3. Run commands: devcontainer exec --workspace-folder ../worktrees/<branch> <command>

Developer Experience Checklist

The devcontainer must support:

• One-command build
• One-command test (all levels)
• One-command run
• Debugger attachment
• Auto-install dependencies on container start
• Local config via .env (not production credentials)

Dependency Installation Policy

All dependencies must be reproducible. Agents must never install packages ad-hoc at runtime.

✅ Allowed	❌ Prohibited
Add to pyproject.toml / package.json then run uv sync / npm ci	pip install, npm install <pkg>, apt install at runtime
Add devcontainer features in devcontainer.json	Manual tool installation in a running container
Add system packages to postCreateCommand	One-off curl | bash installs
terraform init (downloads providers per lockfile)
uv sync / npm ci (installs from lockfile)

When a task requires a new dependency: update the declarative config (pyproject.toml, devcontainer.json, Dockerfile), rebuild the container if needed, then use the dependency. The container must be reproducible from its config files alone.

postCreateCommand Examples

// TypeScript
"postCreateCommand": "npm ci"

// Python with uv
"postCreateCommand": "uv sync"

// Rust
"postCreateCommand": "cargo fetch"

// C/C++
"postCreateCommand": "apt-get update && apt-get install -y build-essential cmake"