Machines

Machines

The question everyone asks first: what is a container machine, and does it run my containers? No. A machine is a persistent Linux workspace — somewhere you work, not a controller for anything else.

Containers vs machines

	Container	Container machine
Modelled after	An application	A Linux environment
Lifetime	Ephemeral — runs one thing, often removed after	Persistent — changes inside it stick
Init	Runs your process (nginx, postgres)	Runs the image's init system (systemd, OpenRC), so it can host services
Identity	The image's user, often root	Mapped to your macOS username, with your home directory shared in
Typical use	Package and run a service	Work inside Linux: build, test, run a toolchain

A machine has no container daemon inside it. It can't start, stop or exec into your containers. It's a VM you log into, like a remote dev box or a WSL distro.

There is one relationship: a running machine gets an address on the same virtual network as your containers, so it can reach them over the network. That's connectivity, not control.

What machines are good for

• Edit on the Mac, build inside Linux. Your home directory is mounted at /Users/<username> inside the machine, so there's no copy step.
• Real Linux services. On an image with systemd, systemctl start postgresql works.
• One machine per distribution. Separate alpine, ubuntu and debian machines with the same home directory and dotfiles, for testing across distributions.
• A durable scratch space that survives stop and start.

Creating one

Machines ▸ +. The image must include an init system at /sbin/init:

• alpine works out of the box.
• A plain ubuntu or debian image does not — it has no init.

To get a machine-ready image, build one under Images ▸ Build Image….

Fields are the name, image, CPUs, memory, whether to mount your home directory, whether to make it the default machine, and whether to boot it after creating.

Using one

Select a machine for:

• Details — status, address, image, resources. CPUs, memory and the home-mount can be changed; they apply on the next stop and start.
• Terminal — an interactive shell inside the app, as your own user, in your shared home directory. Open in Terminal does the same in Terminal.app.
• Logs — boot output, which is where to look when a machine won't start.
• Default — the starred machine, used where a command needs one implicitly.

Machines run under container's background services, so they keep running after you quit the app. Stop one explicitly when you're done; after a reboot they come back stopped.

When a machine won't boot

Almost always a missing init system. The logs will show the kernel starting and then nothing useful, or a panic about being unable to execute /sbin/init. Build an image with one — see building a machine image — rather than trying to fix it from inside.

The first time you open a terminal

Opening a shell in Terminal.app uses AppleScript, so macOS asks for permission to control Terminal the first time. If you decline, the app falls back to opening a .command file, which needs no permission. To grant it later: System Settings ▸ Privacy & Security ▸ Automation ▸ ContainerManager.

The Terminal tab inside the app needs no permission at all.