Table of Contents

• About The Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Commands
  • Example
  • Limits
• Tests
• Roadmap
• Contributing
• License
• Contact
• Acknowledgments

About The Project

This project is unofficial. It is an independent extension, and it is not affiliated with, endorsed by, or supported by Apple or Microsoft. Apple Container, Dev Containers, and VS Code are named only to describe what this extension works with.

The Dev Containers extension shells out to whatever dev.containers.dockerPath points at. Apple's container CLI is OCI-compatible, and it does not speak the Docker CLI. Pointing dockerPath at container itself does not work.

This project is a VS Code extension plus bin/container-docker, a translator for the Docker commands that extension actually runs: build, run, exec, inspect, ps, events, volumes, and the surrounding lifecycle commands. buildx version fails on purpose, so Dev Containers uses classic docker build, which maps onto container build. Feature installs then copy files into the build context.

dev.containers.dockerPath is an application setting. The engine you pick applies to every Dev Container until you switch back.

(back to top)

Built With

(back to top)

Getting Started

Install the extension from this folder, then point Dev Containers at the shim.

Prerequisites

• A Mac with Apple silicon
• Apple Container on PATH (container 1.6.0 or newer)
• Node.js 22 or newer
• Cursor, with the Dev Containers extension

Confirm the CLI:

container --version
container system status

Installation

1. Clone this repository and install it.

   npm install
   npm run compile
   

2. In Cursor, run Developer: Install Extension from Location… and choose this folder.
3. Reload the window.
4. Run Apple Container: Use for Dev Containers.

The status bar shows Apple Container while the shim is selected, and Docker after you switch back.

You can set the path yourself. Use the absolute path to bin/container-docker:

"dev.containers.dockerPath": "/absolute/path/to/container-devcontainers/bin/container-docker"

Apple Container: Use Docker Again sets that value back to docker.

(back to top)

Usage

Open a folder that has a devcontainer.json. Click Apple Container in the status bar, or open the command palette, and run Apple Container: Reopen in Container.

That command points Dev Containers at the shim, then runs the normal Dev Containers reopen flow. Rebuild and related actions do the same. If the folder has no devcontainer.json, the extension stops with an error instead of showing a stuck progress toast.

The shim starts container system services when container system status is not already running.

Commands

Example

examples/hello is a small Alpine container.

{
  "name": "Hello",
  "build": {
    "dockerfile": "Dockerfile"
  },
  "workspaceFolder": "/workspace",
  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
  "postCreateCommand": "sh hello.sh"
}

Open examples/hello and run Apple Container: Reopen in Container. The post-create script writes hello from the dev container to the terminal output of that step.

Alpine images need libstdc++ for the Cursor server. The example Dockerfile installs it. The shim also runs apk add --no-cache libstdc++ when the library is missing, and it puts a flock wrapper on PATH because BusyBox flock rejects the -w timeout the server installer uses.

Limits

• One engine at a time. dockerPath applies to every Dev Container.
• Docker Compose is not supported. docker compose fails with an explicit error.
• GPUs are not supported. --privileged maps to --cap-add ALL.
• --security-opt, --hostname, --add-host, and --pull on docker run are ignored.
• There is no Docker socket. The Containers side panel can keep reporting that Docker is unavailable.
• container build has no --build-context or --cache-from. Features use the in-context copy path.

(back to top)

Tests

npm test
npm run test:smoke

npm test compiles the project and runs the unit tests against a fake container binary. npm run test:smoke runs @devcontainers/cli against the Apple Container CLI installed on this Mac: an Alpine image container and a Dockerfile build. Smoke tests share one container service, so they run one at a time.

(back to top)

Roadmap

• [x] Docker CLI shim for the Dev Containers command set
• [x] Extension commands to switch dockerPath
• [x] Reopen and rebuild through the Dev Containers commands and the shim
• [x] Alpine flock -w and libstdc++ workarounds for the Cursor server
• [ ] Docker Compose
• [ ] GPU passthrough
• [ ] A Containers side panel that does not expect a Docker socket

(back to top)

Contributing

1. Fork the project.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push the branch (git push origin feature/amazing-feature).
5. Open a pull request.

Run npm test before opening the pull request. Run npm run test:smoke when a change touches build, run, or exec translation.

(back to top)

License

Distributed under the MIT License. See the LICENSE file for the full text.

(back to top)

Contact

This project does not have a public remote yet. Open an issue on the repository you cloned it from.

(back to top)

Acknowledgments

• Apple Container
• Development Containers and @devcontainers/cli
• Best-README-Template
• Shields.io

(back to top)