devcontainer

Run VS Code-compatible Development Containers on Apple silicon through stock apple/container, with first-class support for container-compose.

The project's north-star goal is 100% behavioural parity with Docker-based Development Containers, with comparable or better user-visible performance. Current releases make narrower evidence-bound claims until the complete specification and performance objectives are proved. The audited findings and solution designs are in the full parity and performance roadmap.

Important

Version 1.0.1 is the latest immutable stable baseline. Its exact tag certification ran all 18 CLI fixtures plus the real VS Code end-to-end fixture against real Docker, unmodified Apple container 1.1.0, and the separately maintained container-compose 0.10.1 provider stack with zero normalized semantic differences. COMPATIBILITY.md records the newer exact fingerprints required by the current source candidate without rewriting that historical release evidence.

See it work

The recording starts the local compatibility endpoint, runs the official @devcontainers/cli against the checked-in hello example, executes its lifecycle hook, reads the mounted workspace from the running Apple container, and proves exact cleanup. It is generated from docs/devcontainer-demo.tape with VHS; every displayed result comes from the live command immediately above it. Recreate it on a release host with make demo.

Design promise

The project keeps the official Dev Containers toolchain above a local Docker Engine compatibility service. VS Code and the reference @devcontainers/cli remain unmodified; the service translates their tested Docker API subset into Apple-native runtime operations.

flowchart LR
    VS["VS Code Dev Containers"] --> DC["Official @devcontainers/cli"]
    DC --> Docker["Unmodified Docker CLI"]
    Docker --> API["Local Docker Engine compatibility socket"]
    API --> Shared["container-engine generated API 1.44 through 1.53 gateway"]
    Shared --> Session["Private fingerprint-bound provider session"]
    Session --> Core["devcontainer stock adapter and provider-neutral runtime core"]
    Core --> Stock["Stock apple/container"]
    DC --> ComposeChoice{"Compose provider"}
    ComposeChoice --> DockerCompose["Docker Compose over the bridge"]
    ComposeChoice --> ContainerCompose["container-compose adapter"]
    DockerCompose --> API
    ContainerCompose --> Stock

Loading

The container-compose integration is first-class but independently installed. The core does not import ComposeCore, and installing this project never silently replaces stock Apple container with the matched fork stack.

Compatibility target

Lane	Purpose	Stable-release requirement
Real Docker	Behavioral oracle using pinned Docker Engine, Docker Compose, and @devcontainers/cli	Complete raw and normalized evidence
Stock Apple	Official apple/container only; Docker Compose uses the compatibility API	Zero semantic differences in every claimed fixture
container-compose provider	Stephen Clarke's separately installed container-compose, with its exact runtime provenance recorded	Zero semantic differences in every claimed fixture

The test plan covers image, Dockerfile, Features, users, environment, lifecycle hooks, workspace mounts, ports, reuse, Compose services, networks, volumes, failure recovery, and real VS Code attach/rebuild behavior. See TESTING.md, COMPATIBILITY.md, and the explicit standards conformance audit.

Stock apple/container 1.1.0 does not expose create-time hostname, full Docker privileged mode, or most Docker security-option fields. Requests for those semantics fail before runtime creation; privileged mode is never approximated with CapAdd ALL. Runtime-affecting container, exec, network, and volume request objects use strict nested decoding. Unknown fields return a Docker 400, and known fields that the selected runtime cannot enforce return 501, before side effects. Arbitrary runArgs remain outside the compatibility claim until their exact behaviour is certified. See CONFORMANCE.md before using security, device, resource, or advanced mount options.

Project layout

Path	Purpose
USER_GUIDE.md	Installation-to-operation user manual for the stock and optional provider paths
DESIGN.md	Implemented architecture, data flow, runtime boundaries, security, and release definition
PARITY-ROADMAP.md	North-star parity and performance criteria, audited defects, and designed solutions
UNSUPPORTED-CAPABILITIES.md	Field-by-field implementation and certification design for every current unsupported capability
CONFORMANCE.md	Complete audited Dev Containers property ledger and explicit 1.0.1 non-conformances
PERFORMANCE.md	Full repeated-run parity timing analysis and optimization priorities
TESTING.md	Docker, stock Apple, and separate container-compose differential harness
QUALITY.md	Software-quality analysis, measurable gates, and supply-chain controls
BUILD.md	Current local build, test, coverage, sanitizer, parity, and package commands
INSTALL.md	Source, prebuilt, Homebrew, provider, and uninstall contract
RELEASE.md	CI/CD, GitHub Pages, release authority, and Homebrew tap design
COMPATIBILITY.md	Compatibility contract and explicit claim policy
SECURITY.md	Private vulnerability reporting and supported-version policy
Tests/Parity	Machine-readable parity manifest and executable differential fixtures
Examples/hello	Minimal image-based Dev Container used by the live demonstration
container-engine-api 0.3.3 published baseline	Shared executable, generated 107-operation Docker API 1.44 through 1.53 ledger, wire/router/server contracts, schema-2 private provider-session transport, bounded raw/WebSocket streaming, deterministic listener ownership/shutdown, and provider-owned immutable state-root identity. The logging-handoff source requires the coordinated unpublished Engine API/Container stack recorded in the Compose logging design; it is not representable by the published baseline yet.
Sources/DevContainerDockerAPI	Stock-provider Docker Engine endpoint policy and DTO projection
Sources/DevContainerAppleRuntime	Stock Apple runtime adapter and process/port/archive support
Sources/DevContainerService	Stock-provider adapter; normal mode starts one internal private provider session behind the shared public gateway, while --provider-socket exposes only the private session for an external container-engine process
Sources/DevContainerComposeProvider	Optional external container-compose dispatcher

Development

Requirements are Xcode 26, Swift 6.2 or newer, Python 3, Ruby 2.7 or newer (including its standard JSON and Psych YAML libraries), and make. Runtime parity additionally requires a physical Apple-silicon Mac on macOS 26, stock Apple container, real Docker, the pinned Dev Container CLI, and the selected Compose provider.

The stock multi-service path uses the upstream docker-compose client over this project's compatibility socket. The separately selected container-compose provider remains optional and independently installed.

make check
make test
make docs
make serve-docs
DEVCONTAINER_VSCODE_LIVE=1 make parity-vscode-docker

Use devcontainer diagnostics --output devcontainer-diagnostics.tar.gz to create a bounded, privacy-redacted support archive whose JSON manifest is printed before the archive is written.

Live runtime tests are deliberately not run on public pull-request code or GitHub-hosted macOS. They execute on an isolated physical runner only after a trusted exact commit has passed hosted checks.

Documentation

Start with the user guide, then consult the compatibility contract, standards conformance audit, full parity and performance roadmap, and parity timing analysis. The generated DocC site in the Container developer API collection contains the public Swift API reference plus architecture, use, compatibility, conformance, testing, and performance articles. GitHub Pages publishes it from the exact main commit that passes the documentation workflow.

Primary upstream references

The design follows the maintained sources in the Dev Containers GitHub organization:

• Development Containers Specification
• Dev Container CLI reference implementation
• Dev Container Features
• Dev Container Templates
• Dev Container Images
• Dev Container CI
• containers.dev specification and supporting tools

Runtime references are Apple container, Apple containerization, and the Apple container API documentation. VS Code behavior is documented in Developing inside a Container.

Install

Requirements are an Apple-silicon Mac running macOS Tahoe 26 or later and Apple container 1.1.0. Install Apple's signed package first, then install devcontainer:

When macOS asks whether the selected runtime's container-runtime-linux may find and connect to devices on the local network, choose Allow. Stock mode uses Apple's signed helper; the optional provider stack uses its separately installed helper. macOS can list them as distinct Local Network entries. Denying either helper leaves its host listener open but resets connections with No route to host.

brew tap stephenlclarke/tap
brew trust --tap stephenlclarke/tap
brew install stephenlclarke/tap/devcontainer
/usr/local/bin/container system start
brew services start stephenlclarke/tap/devcontainer
devcontainer doctor --container /usr/local/bin/container

Use the compatibility socket only in the shell that needs it:

eval "$(devcontainer context)"
npx --yes @devcontainers/cli@0.88.0 up \
  --workspace-folder /path/to/project

For VS Code, configure the Compose wrapper once and launch the workspace from that configured shell:

{
  "dev.containers.dockerComposePath": "/opt/homebrew/bin/devcontainer-compose"
}

eval "$(devcontainer context)"
code /path/to/project

Optional Apple CLI plug-in registration is explicit and reversible:

devcontainer plugin register
container devcontainer doctor

The stable formula installs this project with upstream Docker CLI and Docker Compose protocol-client dependencies; it does not install a container runtime. Plug-in registration is an explicit, reversible symlink into the active runtime's reported install root, and it never replaces a foreign registration. container-compose remains an explicit optional installation and provider choice. See INSTALL.md for stock/custom runtime selection, service management, upgrades, verification, troubleshooting, and removal.

Independence and trademarks

This is an independent open-source project. It is not affiliated with or endorsed by Apple, Docker, Microsoft, or the Dev Containers maintainers. Apple, Docker, Visual Studio Code, and other marks belong to their respective owners.

License

Licensed under Apache License 2.0, matching apple/container and apple/containerization. The package builder includes third-party notices, deterministic build metadata, checksums, and an SPDX 2.3 SBOM.