devcontainer

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

Important

Version 1.0.1 supports the exact component fingerprints in COMPATIBILITY.md. Release 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.

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 --> Core["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 or Docker security-option fields. A non-empty hostname and security options that are not already Apple’s native state fail before runtime creation. Stock privileged mode maps to Apple’s --cap-add ALL model and is not full Docker privileged mode. Version 1.0.1 also does not fail closed for every unknown Docker create member, so arbitrary runArgs are outside the compatibility claim. 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
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
Sources/DevContainerDockerAPI	Docker Engine API compatibility router
Sources/DevContainerAppleRuntime	Stock Apple runtime adapter and process/port/archive support
Sources/DevContainerService	Unix-socket compatibility engine
Sources/DevContainerComposeProvider	Optional external container-compose dispatcher

Development

Requirements are Xcode 26, Swift 6.2 or newer, Python 3, 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, and parity timing analysis. The generated DocC site 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.