Development Environment Repository

This repository provides a lean development container template for GitHub Codespaces and local VS Code Dev Containers.

Features

• Ubuntu 26.04 (Resolute) base image
• Single-image devcontainer build based on .devcontainer/Dockerfile
• Core tooling for general development work:
  • Python 3 with venv and pip
  • Node.js LTS with npm
  • GitHub CLI
  • Claude Code CLI (authenticated session persisted across rebuilds)
  • OpenCode TUI installed via updateContentCommand (cached by prebuilds)
  • Bash shell with common utilities
  • Build essentials (gcc, make, and related packages) via base image
• VS Code extensions:
  • Claude Code
  • Python and Pylance
  • GitHub Copilot and Copilot Chat
  • YAML

Performance Optimizations

The devcontainer is tuned for fast Codespaces startup:

• Minimal feature set: only common-utils, sshd, node, github-cli, and claude-code features are installed — Docker-in-Docker and git features are omitted
• common-utils configured with zsh and Oh My Zsh disabled
• curl, wget, jq, and git sourced from the base image — not re-installed in the Dockerfile
• OpenCode TUI installed in updateContentCommand instead of postCreateCommand, so it is cached during Codespaces prebuilds and not re-run on every start
• Claude Code authentication stored in a named volume (claude-code-config-${devcontainerId}) so sign-in survives container rebuilds
• Small, targeted extension set

Approximate startup time: ~45–75 seconds without prebuilds and ~10–25 seconds with prebuilds enabled (actual times will vary by region, plan, and image cache state).

Speeding Up Codespaces with Prebuilds

Codespaces prebuilds cache the fully built container image, installed features, and updateContentCommand output on GitHub's infrastructure. This is the single biggest lever for fast cold-starts.

How to enable

1. Navigate to the repository on GitHub.
2. Go to Settings → Codespaces.
3. Click Set up prebuild configuration.
4. Select the main branch and choose one or more regions closest to your team.
5. Set the trigger to "On every push" (or "On configuration change" for less frequent rebuilds).
6. Save.

The first prebuild takes roughly 3–5 minutes. After that, every new Codespace created from main will start in approximately 10–25 seconds.

Tip: Prebuilds are available on GitHub Team and Enterprise plans, and are free for public repositories up to a certain storage quota.

Usage

GitHub Codespaces

1. Click "Code" button on the GitHub repository
2. Select "Create codespace on main"
3. Wait for the environment to build
4. Run claude in the integrated terminal and follow the authentication prompt

VS Code Local Dev Containers

1. Clone this repository
2. Open in VS Code
3. Click "Reopen in Container" when prompted
4. Run claude in the integrated terminal and follow the authentication prompt

Repository Structure

• .devcontainer/devcontainer.json: main devcontainer definition, features, VS Code extensions, and lifecycle commands
• .devcontainer/Dockerfile: minimal image customization for Python packages
• .github/workflows/ci.yml: CI pipeline — Dockerfile linting, secret scanning, image build (artifact-shared across jobs), devcontainer smoke testing, Trivy vulnerability scanning (gates on CRITICAL), SBOM generation, and scheduled daily security scans
• .github/dependabot.yml: daily updates for GitHub Actions, Docker base images, and devcontainer features
• AGENTS.md: guidance for AI agents and automated contributors working in this repository

Using as a Template

Method 1: GitHub Template

Click "Use this template" button to create a new repository

Method 2: Copy Configuration

cp -r .devcontainer /path/to/your/project/

Customization

Edit .devcontainer/devcontainer.json to add features or tools:

{
  "features": {
    "ghcr.io/devcontainers/features/java:1": {
      "version": "17"
    }
  }
}

To add Docker support when you need it:

{
  "features": {
    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
  }
}

If you add new features or packages, keep the CI smoke test in sync with any new tooling expectations you want validated during the container smoke test.

License

This project is licensed under the MIT License - see the LICENSE file for details.