Dev Containers skill for Codex

A good dev container opens to a working environment in one step: toolchain versions match CI, dependencies install from lockfiles, services the app needs are running, and tests pass with the documented command. The same setup script feeds the dev container, CI and Codex cloud, so a task that passes in one passes in the others.

Inspect first

1. Read AGENTS.md, README, .tool-versions, .nvmrc, .python-version, rust-toolchain.toml, go.mod and CI workflows: these define the versions to match.
2. Look for an existing .devcontainer/ (or .devcontainer.json at the root) and docker-compose*.yml.
3. List services the app needs locally (Postgres, Redis, a queue) and their versions in production.
4. Check the host: Docker Desktop, Podman or Colima; Apple silicon means images must have arm64 variants or builds slow down under emulation.

Layout

.devcontainer/
├── devcontainer.json
├── Dockerfile            # only when Features are not enough
└── compose.yaml          # only when services are needed
scripts/
└── setup.sh              # shared by devcontainer, CI and Codex cloud

Single-container baseline

// .devcontainer/devcontainer.json
{
  "name": "api",
  "image": "mcr.microsoft.com/devcontainers/base:bookworm",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "22" },
    "ghcr.io/devcontainers/features/python:1": { "version": "3.13" },
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "remoteUser": "vscode",
  "containerEnv": { "PIP_DISABLE_PIP_VERSION_CHECK": "1" },
  "mounts": [
    "source=api-node-modules,target=${containerWorkspaceFolder}/node_modules,type=volume"
  ],
  "onCreateCommand": "bash scripts/setup.sh",
  "postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}",
  "forwardPorts": [3000],
  "portsAttributes": { "3000": { "label": "web", "onAutoForward": "notify" } },
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint", "ms-python.python"],
      "settings": { "editor.formatOnSave": true }
    }
  }
}

• Pin Feature major versions (:1) and tool versions; latest drifts away from CI.
• Put node_modules (or .venv, target/) in a named volume on macOS and Windows; bind mounts of large dependency trees are slow.
• The vscode user in the official base images matches host UID on Linux through updateRemoteUserUID (default true), avoiding root-owned files in the repo.

Lifecycle hooks

Hook	Runs	Use for
initializeCommand	On the host, before build	Creating .env from example; avoid heavy work
onCreateCommand	Once, when container is created (also during prebuilds)	Install dependencies
updateContentCommand	After create and when content updates in prebuilds	Refresh deps after lockfile change
postCreateCommand	Once, after create, with user secrets available	Steps needing user credentials
postStartCommand	Every start	Start background services, fix permissions
postAttachCommand	Every editor attach	Rarely needed

Keep hooks idempotent; they rerun on rebuild.

Multi-service with Compose

{
  "name": "api",
  "dockerComposeFile": "compose.yaml",
  "service": "app",
  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
  "shutdownAction": "stopCompose",
  "onCreateCommand": "bash scripts/setup.sh"
}

# .devcontainer/compose.yaml
services:
  app:
    build: { context: .., dockerfile: .devcontainer/Dockerfile }
    volumes: ["..:/workspaces/api:cached"]
    command: sleep infinity
    environment:
      DATABASE_URL: postgres://dev:dev@db:5432/api_dev
  db:
    image: postgres:17
    environment: { POSTGRES_USER: dev, POSTGRES_PASSWORD: dev, POSTGRES_DB: api_dev }
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dev"]
      interval: 5s

Match the database major version to production. The app reaches services by service name (db), not localhost.

The shared setup script

#!/usr/bin/env bash
# scripts/setup.sh - one source of truth for dev container, CI and Codex cloud
set -euo pipefail
corepack enable
npm ci
python -m pip install --upgrade uv
uv sync --frozen

• Make it idempotent, non-interactive and offline-tolerant after the first run.
• Call it from onCreateCommand, from CI before tests, and paste bash scripts/setup.sh into the Codex cloud environment’s setup script field.

Codex cloud parity

• Codex cloud runs tasks in its own container (based on the codex-universal image) and does not read devcontainer.json. Parity comes from sharing the setup script and pinning the same language versions in the environment settings.
• Codex cloud runs the setup script with network access; the agent phase may have network off. Everything tests need (dependencies, generated code, test fixtures) must be installed in setup, not fetched during tests.
• Services such as Postgres are not started for you there; either start them in setup (if installable in the image), use lightweight fallbacks such as SQLite for unit tests, or mark integration tests to skip when the service is absent.
• Record the test command in AGENTS.md so local Codex, the dev container and cloud tasks all run the same thing.

Prebuilt images and CI

npm install -g @devcontainers/cli            # needs network
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . npm test
devcontainer build --workspace-folder . --image-name ghcr.io/acme/api-devcontainer:latest

• Prebuild the image in CI when setup takes more than a few minutes, then reference it with "image" (or cacheFrom) so contributors pull instead of build.
• Run the test suite inside the dev container in CI at least weekly to catch drift.
• Pushing images to a registry is outward-facing; confirm the registry and tag with the user.

Gotchas

• Secrets in containerEnv or committed .env files end up in the repo; use remoteEnv with ${localEnv:VAR} or the editor’s secret store.
• Features install in declaration order only when dependencies are declared; use overrideFeatureInstallOrder if one Feature needs another.
• Docker-in-Docker Feature needs privileged mode; prefer docker-outside-of-docker for local use, and know that both widen the container’s access to the host.
• Changing devcontainer.json requires “Rebuild Container”; changes to the setup script alone do not rerun onCreateCommand.

Verification

• devcontainer up --workspace-folder . succeeds from a clean clone
• devcontainer exec --workspace-folder . <test command from AGENTS.md> passes
• Tool versions inside (node -v, python --version) match CI
• A Codex cloud task in the same repo runs the test command successfully
• Time from clone to green tests recorded (target under 10 minutes cold, under 1 warm)