Skip to content

Command Parity

Jump to bottom
Karthik Vinayan edited this page Jun 24, 2026 · 1 revision

Command Parity

A map of the Docker command surface to dcon. Every entry below is a real dcon command — dcon translates the Docker call to Apple's container runtime and re-renders the output in Docker format. Where the backend genuinely can't provide a feature, dcon returns a clear message instead of silently doing the wrong thing.

For how the translation works, see Architecture. For the warm-pool feature, see Warm Pool. For start/memory numbers, see Benchmarks & Comparison. The README parity section is mirrored here as the canonical reference: https://github.com/o1x3/dcon.

Legend

Symbol Meaning
✅ Full parity — Docker→container flag translation, Docker-style output
≈ Best-effort — works, but synthesized or partial vs. native Docker
🍏 Apple-native extra — no Docker equivalent
⛔ Genuinely unsupported by the backend — returns a clear message

A ⛔ command is still recognized: dcon parses it and exits with an explanation (e.g. "commit is not supported by the backend; build an image from a Dockerfile instead") rather than an unknown-command error, so scripts fail loudly and legibly.

Containers

Container lifecycle & inspection
Command Status Notes
run create start stop restart kill rm ✅ Full Docker→container flag translation
ps stats ✅ Rendered as Docker-style tables
exec logs inspect cp export top port attach wait ✅
container prune ✅ Remove all stopped containers
pause / unpause ⛔ Backend can't suspend a microVM
rename ⛔
commit ⛔ Build an image from a Dockerfile instead
diff ⛔
update ⛔

Both the top-level forms (dcon run, dcon ps, …) and the dcon container … group forms (dcon container ls/list, dcon container run, …) are available with identical behavior.

Warm pool — dcon warm …

Pre-boot single-use Apple-container microVMs so eligible --rm runs exec into a ready VM (~90 ms) instead of cold-booting (~700 ms) — faster than a shared-VM engine, with the same per-container isolation (each member is handed out exactly once, then destroyed).

Command What it does
dcon warm [-n N] IMAGE Pre-boot N warm VMs for IMAGE (default 1)
dcon warm ls List warm members — CONTAINER ID / IMAGE / AGE / STATE
dcon warm prune [IMAGE] Tear down warm members (all, or for one IMAGE)

Available as a top-level command (dcon warm …) with ls and prune subcommands. Env knobs (DCON_WARM, DCON_WARM_DEPTH, DCON_WARM_TTL) and the eligibility rules that decide which runs take the warm path are documented in full on the Warm Pool page.

Setup diagnostic — dcon doctor

dcon doctor (also dcon system doctor) runs a one-shot setup check and prints check / warn / fail with a remediation hint for each:

  • Apple container CLI presence and version
  • Backend services running
  • Guest kernel installed
  • Image builder
  • Whether docker on PATH is symlinked to dcon
  • Warm-pool status

It exits non-zero on a hard failure, so it's safe to gate CI on.

Images & registry

Images, build & registry
Command Status Notes
images ✅ Docker-style table
pull ✅ --max-concurrent-downloads (default 8, env DCON_PULL_CONCURRENCY, clamped 1–32)
push rmi tag save load ✅ save/load available top-level and under image
build ✅ --output/--cache-from comma-bearing values handled via non-splitting flags
buildx build / buildx version ≈ Buildx mapped to the Apple container builder backend
image prune ✅
login logout ✅
history ≈ Reconstructed from the OCI config
search ⛔ No registry-search API in the backend

Cold pull is network- and content-store-bound (Apple's floor, ~13 s for alpine vs ~3 s on a shared-VM engine). dcon raises the default layer-download concurrency from the backend's 3 to 8 (empirical knee; gains past it are <5%). The re-pull speedup comes from blob caching (rmi keeps layer blobs), not from concurrency. See Benchmarks & Comparison.

Volumes · networks · system

Volumes, networks & system
Command Status Notes
volume create / ls / rm / inspect / prune ✅
network create / ls / rm / inspect / prune ✅
version info ✅ Synthesized Docker output
system df system prune ✅ Synthesized Docker output
network connect / disconnect ⛔ Backend can't hot-attach networks
events ⛔ No event stream in the backend

Compose — dcon compose …

A built-in engine parses compose.yaml / docker-compose.yml and maps each service onto a container. Standard com.docker.compose.* labels make dcon ps and dcon compose ls project-aware.

Compose subcommands
Subcommand Notes
up -d, --build, --no-start, --force-recreate
down -v to remove volumes
ps Project-aware
logs -f, aggregated and service-prefixed
build pull
start stop restart kill rm
run exec create
config ls top images version

Bring-up runs one dependency level at a time and, within a level (no ordering constraint), starts services concurrently — capped by DCON_COMPOSE_PARALLEL (default 8; <=0 = unlimited). depends_on ordering is preserved across levels.

Apple serializes VM boots, so a pure-boot stack gains only modestly (~11–16%). Build/pull-heavy stacks (compose up --build) gain more, where the network/builder-bound steps overlap.

Compose keys honored

image · build (context / dockerfile / args / target) · command / entrypoint · environment · env_file · ports · volumes (relative-path resolution) · networks · depends_on (ordering) · labels · working_dir · user · platform · cpus · mem_limit · privileged · cap_add / cap_drop · dns · tty · init · shm_size · tmpfs · read_only · container_name · plus ${VAR:-default} interpolation.

For end-to-end compose recipes (profiles, scaling, multi-arch builds, private registries), see the cookbook: https://github.com/o1x3/dcon/blob/main/SECONDARY.md.

Apple-native extras

Beyond the Docker surface, dcon exposes the backend's own capabilities:

Backend management & native run/build flags
Command / flag group Purpose
dcon machine … Manage the backend machine
dcon builder start / status / stop / rm Manage the image builder
dcon system dns / kernel / property / logs / start / stop / status Backend services and config
dcon system kernel set --recommended Install a guest kernel (one-time setup)
run/build extras: --rosetta --ssh --virtualization --os --arch --kernel --init-image --publish-socket --no-dns --dns-domain Apple-native run/build options with no Docker equivalent

Compatibility shims

Docker flags the backend can't honor are accepted and ignored with a warning (not errors), so existing scripts and compose files keep working unchanged:

Flag Behavior
--restart Accepted, ignored (warning)
--hostname Accepted, ignored (warning)
-P / --publish-all Accepted, ignored (warning)
--add-host Accepted, ignored (warning)
--device Accepted, ignored (warning)
--gpus Accepted, ignored (warning)
--sysctl Accepted, ignored (warning)
--memory-swap Accepted, ignored (warning)
--cpu-shares Accepted, ignored (warning)
--privileged Approximated as --cap-add ALL

The distinction matters: a ⛔ command tells you it can't run; a shimmed flag lets the command run while warning that one option had no effect.

See also

Clone this wiki locally