#4358·earthly

Support apple/container as a macOS container runtime/frontend

Author: gilescopeCreated Jun 23, 2026Updated Jun 23, 2026
Labelsplatform:darwintype:proposalcategory:versatility

Problem

EarthBuild can only run buildkitd via the docker or podman frontends. On macOS, apple/container (v1.0.0, macOS 26) runs OCI containers in per-container lightweight VMs with no Docker daemon — a faster, lower-overhead alternative to Docker Desktop that EarthBuild cannot currently use.

Fix

Add an apple-container ContainerFrontend implementation (the same seam used for Podman in #760), selectable via global.container_frontend.

The runtime backend is already pluggable: util/containerutil/frontend.go defines the ~14-method ContainerFrontend interface with docker.go / podman.go shell impls. A new impl plus a frontend constant is the bulk of the work.

Known blockers (in rough order of risk)

  • buildkitd privilege (load-bearing unknown). apple/container has no --privileged, only --cap-add. Must confirm buildkitd boots rootless / with explicit caps. If it can't, this is shim-only (see Alternatives). Spike this first.
  • gRPC transport. No docker-container:// connhelper exists for apple/container. Use tcp://<container-ip>:<port> (Podman already does TCP). apple/container's host-reachable per-container IP makes this plausible. Extend the scheme allowlist in util/containerutil/shell_shared.go:parseAndValidateURL().
  • Image load. New ImageLoadFromFileCommand variant (cf. Podman's podman pull docker-archive:).
  • Loose ends. Auth provider defaults to ~/.docker/config.json (build_cmd.go); regproxy hardcodes host.docker.internal (regproxy/controller.go) — both need per-runtime values.

WITH DOCKER is not a blocker: dockerd-wrapper.sh runs dockerd inside the buildkit container, independent of host runtime.

Done when

  • Confirmed whether buildkitd runs under apple/container with --cap-add (spike)
  • apple-container frontend implements ContainerFrontend
  • earthbuild bootstrap + a WITH DOCKER build pass on macOS 26 with container_frontend = apple-container
  • Docs note macOS-26-only requirement

Alternatives

  • Compatibility shim (socktainer exposes a Docker REST API over apple/container) — existing docker frontend, ~0 EarthBuild code. Viable near-term, but adds a dependency and inherits apple/container's privilege limits.

Sibling issue: wslc (Windows native runtime) — see linked issue.

AI-assisted investigation.