# Devcontainer Setup

> Templates and process for creating devcontainer configurations. Use this when setting up a new project, adding devcontainer support, or creating devcontainers for worktrees. Use when this capability is needed.

- Skill: `tomevault-io/devcontainer-setup` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/devcontainer-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/devcontainer-setup/raw
- Safety review: WARNING (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/devcontainer-setup

---


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.

```jsonc
// .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).

```jsonc
// .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:

```jsonc
// 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

```jsonc
// 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"
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/peteroden) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->