Apple Dev Container CLI (adevcontainer)

Native Swift CLI that reads devcontainer.json and runs development environments on Apple container.

Use up with an existing checkout, or use clone to keep the repository in a named volume for faster I/O. Work from your terminal, an AI agent or VS Code.

For implementation details and behavior beyond this quick reference, see the technical documentation.

Requirements

• macOS 26+ on Apple Silicon
• Apple container, installed separately

Install

Homebrew (recommended)

brew install wcgomes/tap/adevcontainer

Release binary

Download adevcontainer-macos-arm64.tar.gz and adevcontainer-macos-arm64.tar.gz.sha256 from GitHub Releases, then run:

shasum -a 256 -c adevcontainer-macos-arm64.tar.gz.sha256
tar xzf adevcontainer-macos-arm64.tar.gz
sudo mv adevcontainer /usr/local/bin/ # or move it to another directory on PATH

Verify the installation and Apple container setup:

adevcontainer doctor

To build from source, follow CONTRIBUTING.md.

Quick start

Your project must contain .devcontainer/devcontainer.json or .devcontainer.json.

Use a local checkout

From the project directory:

adevcontainer up
adevcontainer exec -it

Tip: Apple Containers works differently from other container runtimes: it uses a lightweight VM per container instead of sharing one super VM, but its default resources can be low or insufficient for dev containers; if a container is unresponsive, consider setting hostRequirements in devcontainer.json.

To use another local directory, run adevcontainer up -w <path>.

Clone into a named volume

You do not need a local checkout. Use an HTTPS or SSH Git URL:

adevcontainer clone https://github.com/org/repo.git
adevcontainer list
adevcontainer exec --name <name> -it

The cloned source remains in a named volume. You can work, commit, and push from inside the container. If bring-up fails after the config-only fetch, the CLI retains that checkout for recovery. On a TTY it offers to open and retry the config; in automation, edit the printed path and run the exact adevcontainer clone <git-url> --resume <config-dir> command.

Commands

Command	Purpose
adevcontainer doctor	Check Apple container readiness
adevcontainer up [-w <path>] [--vscode]	Create or start a dev container from a local folder
adevcontainer clone <git-url> [--vscode] [--resume <config-dir>]	Clone a repository into a named volume and start its dev container
adevcontainer exec [-it] [--name <name>] [--] [cmd…]	Open a shell or run a command in a running managed container
adevcontainer list [--json]	List managed dev containers
adevcontainer start [--name <name>] [--vscode] [--json] | stop | inspect [--name <name>]	Manage a container by name or with the interactive picker
adevcontainer delete [--name <name>]	Remove a container, keeping its managed volumes
adevcontainer purge [--name <name>]	Remove a container, its managed volumes, and the image
adevcontainer rebuild [--name <name>] [--vscode]	Rebuild a managed container from its current configuration
adevcontainer help [<command>]	Show main usage or per-command help
adevcontainer version [--version]	Print the CLI version

Bring-up recovery

When up or clone cannot bring up a container after an editable devcontainer.json exists, interactive TTY mode prints the structured failure, asks Open the recovery editor now? [Y/n], and retries the complete create path after a valid edit. Declining or EOF returns the original failure. Non-TTY and --json never prompt or edit; up prints a host-config retry hint, while clone retains its config checkout and prints an exact clone --resume command.

If start cannot start a selected managed container, TTY recovery asks the same question and delegates to rebuild --name <name>; it never re-runs start or opens an editor. Non-TTY, --json, decline, and EOF return the original start failure with the rebuild hint.

Visual Studio Code integration

up, clone, and rebuild apply supported customizations.vscode.settings and customizations.vscode.extensions from devcontainer.json by default (soft-fail; not full Dev Containers extension parity). start does not apply settings or extensions.

--vscode only opens a new VS Code window on the remote workspace and gates postAttachCommand. Install the Remote - Containers extension and make sure the code CLI is available:

adevcontainer up --vscode

Contributing

See CONTRIBUTING.md for prerequisites, source builds, tests, fixtures, and the repository development workflow.

Technical design and project decisions are documented in the wiki.

License

This project is available under the MIT License.