Engines

Apple Containers on macOS, Docker or Podman on Linux, and anything that answers the Engine API.

Hopper does not have one engine. It discovers the engines that make sense on this machine, shows them separately, and tells you which one answered.

macOS Apple silicon — Apple Containers

Apple's container ships as part of the macOS 26 story and requires Apple silicon: every container is its own lightweight virtual machine, images are OCI, and Apple maintains it. Hopper installs it, starts and stops its services, and drives it.

This is the default on macOS. If container is not on the machine, Hopper offers to fetch the package Apple signed and hands it to the system installer, which asks you to approve it. Hopper never elevates privileges itself.

Linux — Docker or Podman

Whichever you have. Hopper checks rootless sockets before system ones, so a desktop Podman is not passed over in favour of a stale root daemon:

1. $XDG_RUNTIME_DIR/podman/podman.sock
2. $XDG_RUNTIME_DIR/docker.sock
3. /var/run/docker.sock
4. /run/podman/podman.sock

Podman's socket is deliberately Docker-compatible, so nothing else changes. DOCKER_HOST, when set, wins outright — if you are pointing at a remote daemon you mean it. CONTAINER_HOST is also accepted when DOCKER_HOST is unset.

Windows — Docker Desktop or Podman

Hopper checks Docker Desktop's docker_engine named pipe and Podman's default machine pipe. They are shown as separate choices when both are present, and Hopper attaches to the one you select without taking over its lifecycle.

Anywhere — an engine you already run

Docker Desktop, Colima, Rancher Desktop, or a daemon over TCP. This one is always available and always last, so Hopper stays useful whatever else fails.

When nothing is running

The fallback never disqualifies itself, so landing on it proves nothing is listening. On a platform with an engine of its own, that is exactly when Hopper offers that engine instead of reporting a missing Docker. A Mac with neither Docker nor Apple's runtime gets the install offer, not a dead end about the thing Hopper exists to replace.

It keeps looking, too. An engine that appears after launch — Docker Desktop started by hand, Apple's runtime finishing its install — is picked up by the status poll without restarting Hopper.

What each engine can do

Apple's runtime is not the Docker Engine API, and Hopper does not pretend otherwise. It publishes no Docker socket — the request for one was closed as not planned — so Hopper speaks to it through the container command instead. Some things are simply not there:

Hopper hides what an engine cannot do rather than offering a button that always fails. On Apple Containers the detail pane shows Logs and Inspect instead of five tabs where three cannot load.

Compose is the exception, and deliberately so. Apple ships none and publishes no socket for the real one to reach, so rather than hide the feature Hopper reads the compose file and creates the containers itself — see Stacks.

If you need any of it, switch engines under Settings → Engine.

Choosing one yourself

HOPPER_ENGINE overrides everything, then the saved setting, then the platform default:

HOPPER_ENGINE=existing /Applications/Hopper.app/Contents/MacOS/hopper

Valid ids depend on the platform. The common ids are existing, docker, and podman; macOS also offers apple, colima, and rancher when those engines are supported by the host.

An engine you name is honoured even when it cannot run yet — Hopper reports on the one you asked for and what it needs, rather than quietly answering about a different one.