Run Dev Containers anywhere you have Linux and Docker.

devcontainer is a self-contained CLI for starting development environments from devcontainer.json in CI, remote development hosts, and internal developer platforms. It ships as a single static binary, requires no Node.js runtime, and is behaviorally compatible with the official @devcontainers/cli within its supported scope.

Use it to give developers and automation the same reproducible environment, add Dev Container support to Linux hosts without managing Node.js, and build prebuild workflows without reimplementing Dev Container behavior.

• I already have a Dev Container: install the binary, run devcontainer up, and follow the migration guide for compatibility details.
• I want to use Dev Containers in CI: see the CI workflow for a minimal build-and-run example.
• I am building a remote development platform: see the platform workflow for prebuilds, deterministic cache keys, lifecycle management, and editor hand-off.
• I am evaluating compatibility: read the supported scope and deliberate divergences.

The official CLI remains the compatibility reference. This project focuses on portable distribution and operational workflows around it.

Download the archive for your architecture from the Releases page, extract devcontainer, and place it on your PATH:

tar xzf devcontainer_<version>_linux_<amd64-or-arm64>.tar.gz
chmod +x devcontainer
sudo mv devcontainer /usr/local/bin/
devcontainer --version

See Installation for checksum verification, building from source, prerequisites, and the OCI image's intended use.

From a repository that contains .devcontainer/devcontainer.json:

devcontainer check
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . sh -lc 'printf "ready: %s\n" "$USER"'

up builds or pulls the configured image, installs Features, starts the container, and mounts the workspace. exec runs a command in that environment.

If you do not have a Dev Container configuration yet, start with the Dev Container specification and templates.

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . sh -lc './scripts/test'
devcontainer down --workspace-folder .

devcontainer up --workspace-folder .
devcontainer open --workspace-folder .

The editor reconnects to the provisioned container instead of creating a separate one.

devcontainer read-configuration --workspace-folder . --cache-key
devcontainer up --workspace-folder . \
  --cache-image ghcr.io/acme/project-dev:sha-abc123

The cache key represents the resolved configuration and build inputs. A platform can use it to select a prebuilt image without reproducing the CLI's hashing logic. See Use cases for a complete workflow.

This project supports and validates:

• Linux on amd64 and arm64.
• Docker Engine API v1.44 or newer (Docker 25+).
• Docker Compose v2 for Compose-based configurations.
• The core up, build, exec, read-configuration, run-user-commands, features, and templates command families.

Windows, macOS, Podman, Docker Compose v1, and legacy Feature fallback through GitHub Releases are not supported targets. “Compatible” means compatibility within this scope; it does not mean that every platform or historical upstream behavior is implemented.

A pinned official TypeScript CLI (reference/, currently v0.90.0) is the behavioral oracle. Roughly 200 cases run commands through both CLIs and compare exit status, normalized output, and relevant container or registry state. See the parity matrix and documented divergences.

devcontainer check
devcontainer setup
devcontainer open .
devcontainer stop .
devcontainer down .

devcontainer read-configuration --workspace-folder . --cache-key
devcontainer up --workspace-folder . --cache-image <image>
devcontainer build --workspace-folder . --secrets-file secrets.json

The Go-only features reference documents their behavior, flags, limitations, and automation-friendly JSON output.

• Documentation overview
• Installation and prerequisites
• Migrating from @devcontainers/cli
• CI and remote development platform workflows
• Troubleshooting
• Go-only features
• Divergences and accepted limitations

The usual local development loop is:

task build
task test:unit
task test:integration
task lint

Parity and Docker-backed suites have additional prerequisites:

git submodule update --init reference
task reference
task parity:contract
task test:e2e
task parity:runtime

Coverage is kept separate by execution layer so a broad Docker or parity suite cannot hide a regression in fast unit coverage. Run task --list for all development, coverage, compliance, and release tasks.

Releases use v-prefixed CalVer tags (vYYYYMMDD.NN) and publish static archives, checksums, SBOMs, and the signed multi-architecture image.

See LICENSE.txt.