Images and Builds

Images and builds

The Images section lists what's stored locally, pulls new ones, builds from a Dockerfile, moves images between Macs as archives, and finds the ones nothing is using.

Pulling

Images ▸ + takes a reference such as docker.io/library/postgres:16 and pulls it with progress. Cancel actually cancels.

An unqualified name is assumed to be on Docker Hub, so alpine means docker.io/library/alpine.

Building from a Dockerfile

Images ▸ Build Image… runs container build and tags a local image, local/<name>:latest by default. The result is an ordinary image, selectable anywhere a reference is.

The build library

Every build is saved so you can come back to it:

~/Library/Application Support/ContainerManager/Builds/<name>/
    Dockerfile
    …            # anything else you add

• The name you give a build is its folder name; Load saved build lists them.
• Reveal in Finder opens the folder.
• That folder is the build context, so COPY and ADD resolve against files you put there.

Environment variables

Set environment variables takes KEY=value lines, or Import from File… for a .env. Each entry is applied both ways, because a Dockerfile may use either:

• as --build-arg, picked up by a matching ARG, and
• as an ENV default baked into the image, so containers run from it inherit them.

SSH agent forwarding

Forward SSH agent to the build lets a Dockerfile reach private repositories with RUN --mount=type=ssh …. Your agent is forwarded for the duration; no key is written into the image.

Stopping a build

A build can run for minutes. Stop interrupts it, and closing the sheet stops it too rather than leaving it running with nowhere to report.

Building a machine image

Machines need an init system at /sbin/init. To build a suitable image:

1. Images ▸ Build Image…, name it (e.g. ubuntu-machine).
2. Write a Dockerfile that installs an init system.
3. Build, then Create Machine from Image.

This is the in-app version of Apple's bring your own container machine image flow.

Archives — moving images between Macs

Right-click an image:

• Save as Archive… writes an OCI archive with layers and configuration included.
• Load from Archive… reads one back.

This is how to move an image to another Mac, or keep one that isn't in a registry.

Not to be confused with Export Filesystem… on a container, which writes the files only — no layers, no image configuration — and has no matching import. Useful for looking inside a container or pulling files out of it; not a backup. Reach for an archive if you want something restorable. (Needs container 1.2.1.)

Unused images

Images that no container and no machine references are badged Unused, and Delete Unused Images… clears them out.

Stopped containers still count as references. This is why deleting an image can appear to free nothing while something still holds its data — the layers are shared, and they go when the last reference does.

Grouping

The Images list groups by what uses each image — a stack's name, Shared when more than one thing uses it, Unused when nothing does. Group headers collapse and stay collapsed, and right-clicking one acts on the whole group.