dockma

Lightweight Docker on macOS, free and open source. Website and command reference: https://dockma.dev

tl;dr

dockma runs the Docker Engine in a minimal Linux VM on Apple's Virtualization.framework. The macOS docker CLI communicates via a Unix socket. A launchd job keeps it running, and your home directory is shared into the VM.

Status: early and experimental, tested only on Apple Silicon with macOS 27. Read the Limitations.

Features

Feature	What you get
Minimal guest	A custom 6.18 LTS kernel with only what Docker needs, no modules, and a busybox initramfs with Docker's static binaries. Docker is ready about 1.0 s after boot starts.
Shared home	$HOME is mounted into the VM at the same path, so docker run -v "$PWD:/src" works anywhere under it.
Ports on localhost	-p 8080:80 answers on localhost:8080 (IPv4 and IPv6), UDP included. Ports below 1024 work too (details).
Containers reach the Mac	host.docker.internal and --add-host name:host-gateway resolve to the Mac, as on Docker Desktop. A Mac service must listen on more than 127.0.0.1 to be reachable.
amd64 images	--platform linux/amd64 runs through Rosetta for Linux.
Runs in the background	A launchd job keeps the VM up and restarts it if the guest crashes.
Shell in the VM	dockma shell opens a root shell, even when dockerd is broken.
Graceful shutdown	dockma stop powers the guest off cleanly. Images, containers and volumes persist on a sparse disk image.

Requirements

• An Apple Silicon Mac, macOS 14 or later (only macOS 27 is tested).
• The docker CLI, e.g. brew install docker. dockma provides the engine, not the client.
• Optional: Rosetta for amd64 images (softwareupdate --install-rosetta).
• Building from source also needs Xcode with Swift 6.4, and an arm64 Docker engine with buildx for the guest (Lima, Colima, Docker Desktop, or dockma itself once it runs). The guest build downloads from kernel.org, download.docker.com, GitHub, Docker Hub and the Go module proxy.

Quick start

With the install script

curl -fsSL https://dockma.dev/install.sh | sh
dockma start
docker context use dockma

install.sh installs the newest release:

1. It downloads the CLI tarball and checks it against the release's SHA256SUMS, and against its build attestation when a logged-in gh is available.
2. It fetches the matching guest with dockma install. If that fails, nothing changes.
3. It installs dockma and its daemon dockmad to ~/.local/bin, and tells you if that isn't on your PATH.

It doesn't start the VM or edit your shell profile. Run it again to upgrade.

Variable	Effect
DOCKMA_VERSION	Install this release (0.3.0 or later) instead of the newest
DOCKMA_INSTALL_DIR	Install the binaries here instead of ~/.local/bin
DOCKMA_SKIP_GUEST=1	Install only the CLI; run dockma install later
DOCKMA_RELEASE_URL	Read release assets from this URL or absolute path instead of GitHub. Needs DOCKMA_VERSION; dockma install reads it too.

From a release

Each release has the CLI (dockma-<version>-macos-arm64.tar.gz), the guest (dockma-linux-<version>-arm64.tar.gz) and SHA256SUMS.

shasum -a 256 -c SHA256SUMS --ignore-missing
xattr -d com.apple.quarantine dockma-*-macos-arm64.tar.gz   # only if a browser downloaded it
mkdir -p ~/.local/bin
tar -xzf dockma-*-macos-arm64.tar.gz -C ~/.local/bin dockma dockmad
dockma install          # fetches and verifies this version's guest into ~/.dockma/guest
dockma start
docker context use dockma

• The binary is ad-hoc signed, not notarized. macOS kills a quarantined copy at launch, hence the xattr step for browser downloads.
• gh attestation verify <file> --repo <owner>/dockma checks that a tarball came from this repository's release workflow.
• dockma install replaces the guest atomically; a running VM keeps the old one until dockma restart.
• dockma start (and restart) runs dockma install itself when no guest is installed, or when the installed one came from another release. It never replaces a guest from make install-guest or one installed before 0.6; DOCKMA_NO_AUTO_INSTALL=1 turns it off. Offline, unpack the guest tarball into ~/.dockma/guest yourself.

From source

make guest install-guest     # build the guest kernel and initramfs, copy them to ~/.dockma/guest
make install                 # build, sign and install ~/.local/bin/dockma and dockmad
dockma start
docker context use dockma    # or: export DOCKER_HOST=unix://$HOME/.dockma/docker.sock
docker run --rm hello-world

Never use plain swift build. It produces a dockmad without the com.apple.security.virtualization entitlement, which dockma start refuses to run, and binaries without the signing identifiers the CLI and daemon check on each other. Use make build or make install.

A DOCKER_HOST that is already set (Lima sets one, for example) overrides docker contexts. Unset it or point it at dockma's socket; dockma start and dockma status warn about it.

Usage

Command	Does
dockma install	Download this version's guest into ~/.dockma/guest
dockma start [--timeout <s>]	Start the VM and wait until Docker answers
dockma stop	Shut the VM down gracefully
dockma restart [--timeout <s>]	Stop, then start
dockma status [--json]	State, uptime, resources, kernel, forwarded ports
dockma shell [-t|-T] [-- cmd …]	Root shell in the VM, or run one command there
dockma logs [--docker|--daemon] [-n N] [-f]	VM console log, dockerd's log, or the host daemon's log
dockma config [options]	Show or change settings
dockma delete [-f]	Delete the data disk (all images, containers, volumes), config and logs
dockma --version	Print the version

This is the beginning of the README. Read the rest at the original. Read the full README ↗