Project study / Platforms
Published
Harpoon
A Docker-compatible macOS runtime that runs Linux workloads without requiring Docker Desktop.
Harpoon owns the macOS-to-Linux boundary while leaving container behavior to Docker Engine inside a minimal guest.
Runtime boundary / host to guest
- Docker CLI
- Host API / socket
- macOS runtime
- Virtualization.framework
- Linux VM
- Docker Engine
01 / Constraint and response
Developers want a Docker-compatible workflow on macOS without making Docker Desktop the required virtualization layer.
Approach
Harpoon runs a small Linux appliance and bridges Docker CLI and Compose workflows through a Unix socket and Docker context to the Engine inside it.
System boundary
The macOS host manages lifecycle, networking, diagnostics, socket bridging, and bind mounts through Virtualization.framework; the guest Docker Engine remains authoritative for containers.
02 / Architecture notes
Host and Guest Boundary
Harpoon owns the macOS host boundary and VM lifecycle; Docker Engine, containerd, and BuildKit own container resources inside Linux.
- 01
Docker Engine 28.3.3 inside the Alpine guest is authoritative; Harpoon is the host control plane rather than a second container runtime.
- 02
The current desktop release is 0.1.1; Apple Silicon support, ad-hoc signing, and occasional Virtualization.framework startup conditions remain visible limits.
03 / Current state
What exists, and what follows.
Published
September 2026
Compatibility improves when a replacement runtime preserves familiar client interfaces and clear ownership boundaries.
Next direction
- Complete Developer ID signing and notarization, then continue broader host validation and lifecycle, networking, and diagnostics work.