Container Machines: A Persistent Linux Environment on Mac

Apple’s container tool reached 1.0 during WWDC week, and the headline feature answers a gap Mac developers have worked around for years: container machine, a persistent Linux environment that behaves like part of macOS.² The WWDC session introducing it compresses the pitch into one sentence: “A Container machine is fast and lightweight, like a container, and persistent like a virtual machine.”¹ Your repositories and dotfiles are available on both sides, the login user matches your Mac account, and the machine keeps its filesystem between sessions, so the Linux toolchain you set up on Tuesday is still there on Friday.³

Session 389, “Discover container machines.”

TL;DR

• container machine ships in container 1.0.0, released on GitHub during WWDC week. It provides “long-lived Linux environments with tight host integration” on top of the Containerization framework Apple open-sourced at WWDC 2025.²
• Where containers are “modeled after an application,” a container machine is “modeled after a Linux environment”: it runs the image’s own init system, persists filesystem changes, and is created from standard OCI images.³
• Host integration is the differentiator. The Linux login user matches your Mac account with passwordless sudo and your home directory is mounted inside the machine,⁴ and an interactive shell drops you into the same working directory you came from on macOS.¹
• The full subcommand set is create, run, list, inspect, set, set-default, logs, stop, and delete, with m as the short alias.⁴
• The 1.0 release also makes one breaking change worth knowing before you upgrade: a TOML configuration file at ~/.config/container/config.toml replaces the old UserDefaults-backed system properties, and the container system property subcommands are gone.²

A Linux environment, not an application sandbox

Apple’s documentation draws the line precisely: “Containers are typically modeled after an application. A container machine is modeled after a Linux environment.”³ The distinction shows up in three behaviors. A container machine runs the image’s own init system, such as systemd or openrc, so you can register long-running services and test your application under a real process supervisor: systemctl start postgresql works the way it does on a Linux box.³ It persists modifications, so tools you install accumulate over time instead of vanishing with the process.¹ And it boots from the same OCI images containers use, so an image you build with container build doubles as the starting point for a machine.¹

The pull request that landed the feature states the motivation plainly: container runs each workload in an ephemeral VM, so before 1.0 there was no built-in way to keep a persistent Linux environment you could log into and work in.⁴ Underneath, each container machine still gets the Containerization treatment: its own lightweight virtual machine with VM-based isolation and the sub-second start times the framework was built around.¹

The session frames the design goals in workflow terms: switching between macOS and Linux should be easy, environments should be quick to create, and “quick creation allows multiple projects to have their own, dedicated environment, without the worry of conflicting dependencies or toolchains.”¹ One machine per target distribution is an intended pattern, and each machine sees the same home directory and dotfiles from your Mac.³

The loop: edit on the Mac, build inside Linux

The session demo is a Vapor web server, and the workflow it walks through is the whole point.¹ The project is edited in Xcode on macOS. The build and run happen inside a container machine with the Swift toolchain installed. Safari on the Mac loads the running server by IP address and port. When the presenter re-exports an app icon from Icon Composer on the Mac and overwrites the file, a browser refresh shows the new asset with no copy step, because the machine and the Mac share the same files.¹

Apple’s docs generalize the pattern: your repo lives in $HOME on macOS and is mounted inside the machine, so macOS-native tooling (profilers, browsers, GUI debuggers) sees the same files the Linux environment sees. As the documentation puts it, there is no copy step between “I built it” and “I am inspecting it.”³

The host integration runs deeper than a shared mount. The machine automatically creates a Linux user matching your Mac username, grants it passwordless sudo, and mirrors your current working directory, so whoami and pwd answer the same inside and outside.¹ The one command that changes its answer is uname: Darwin on the Mac, Linux in the machine.¹

One piece of first-day friction is worth knowing before you hit it: a container machine has an isolated network, and the session is explicit that a server inside it must listen on the external interface before a browser on the Mac can reach it.¹ The demo handles it the way you will: container machine list displays each machine’s IP address alongside its name and resources, the server config binds to that address, and Safari reaches the app at the machine’s IP and port.¹ Plan for the IP-address step in any workflow that serves traffic out of the machine.

The commands

The quickstart is four lines:³

container machine create alpine:latest --name dev
container machine run -n dev whoami       # your host username, not root
container machine run -n dev pwd          # your Mac home directory, mounted in
container machine run -n dev              # interactive shell

container machine run does double duty: with a command it executes once and exits, without one it opens an interactive shell, and if the machine is stopped it boots it first.³ A default machine removes the -n flag from every call:

container machine set-default dev
container machine run                     # operates on dev

Management is the familiar verbs: ls, inspect, logs, stop, and rm, where deleting a machine removes its persistent storage too.³ Resources are adjustable after creation with container machine set -n dev cpus=4 memory=8G, taking effect on the next stop and start; memory defaults to half of host memory, and the home mount can be rw (the default), ro, or none.³ Every command also accepts m as the alias, so m run and m ls work.⁴

Bring your own machine image

Any Linux image that includes /sbin/init works as a container machine.³ Apple’s docs ship a worked Dockerfile that turns ubuntu:24.04 into a machine image with systemd, OpenSSH, and common command-line tools, then masks the systemd units that make no sense inside a lightweight VM.³ You build it with container build and pass the tag to container machine create.

Provisioning has an escape hatch. By default, container runs a built-in setup script on first boot to create the matching user. An executable at /etc/machine/create-user.sh in the image replaces that script; it runs once, as root, on first boot, with CONTAINER_USER, CONTAINER_UID, CONTAINER_GID, CONTAINER_HOME, and CONTAINER_MACHINE_ID set, so an organization can encode its own user setup into a shared base image.³

The rest of 1.0, including the breaking change

The machine feature headlines the release, but 1.0 carries changes that affect existing users.²

The breaking one is configuration. A TOML file replaces the UserDefaults-backed system properties, and the container system property get and set subcommands are removed.² The service reads ~/.config/container/config.toml at startup with first-match-wins precedence (your user file, then an optional file shipped with the package install, then hardcoded defaults), and changes require a service restart to take effect.⁶

The quality-of-life additions: a container cp command for copying files, a --stop-signal option on container run, and cleaned-up structured output (JSON, YAML, TOML) for the ls and inspect commands across containers, images, networks, and volumes.² Networking gets a correctness fix that uses XPC connections as leases to stop IP address leaks.² Compatibility with the version 0 XPC APIs is removed, with a versioned API promised in a later release.²

The requirements hold steady from the 0.x line: a Mac with Apple silicon, running macOS 26. The maintainers state they typically will not address issues that cannot be reproduced on macOS 26.⁵

Why agent workflows should care

A reading from where I sit, not an Apple claim: a container machine is the shape of environment coding agents want. Agents running on a Mac need somewhere to execute builds, run servers, and install dependencies without touching the host: fast to create, isolated by a real VM boundary, persistent enough that a toolchain installed in one session survives to the next. Until now the Mac answers were Docker Desktop-style VMs (heavyweight, one big shared environment) or ephemeral containers (isolated but forgetful). A machine per project, created from a versioned OCI image, with the repo mounted in and passwordless sudo inside, matches how agent sandboxes already work on Linux hosts.

The same property serves plain cross-platform work. Server-side Swift is the obvious beneficiary: the session demo is Vapor, and the Foundation Models framework goes open source this summer with Linux support, so the test environment for “does my Swift code run on Ubuntu” is now one container machine create away. The comparison that will occur to anyone who has used Windows is WSL, and the direction of integration is the same: a real Linux kernel a shell away, with your files visible on both sides. Apple’s version arrives with an image-based workflow already attached.

FAQ

What is a container machine?

A container machine is a persistent Linux environment on macOS, shipped as a feature of Apple’s open-source container tool starting in version 1.0.0.² It runs in its own lightweight virtual machine via the Containerization framework, boots from standard OCI images, runs the image’s init system, and persists filesystem changes between sessions.¹ Host integrations mount your home directory inside, match the Linux user to your Mac account with passwordless sudo, and keep your working directory consistent across the boundary.⁴

How is it different from a regular container?

Apple’s docs put it in one line: containers are “modeled after an application,” a container machine is “modeled after a Linux environment.”³ A regular container run workload is ephemeral and process-centric. A machine is stateful, runs systemd or openrc, and is meant to be revisited over time, like a VM with container creation speed.¹

What does it require?

A Mac with Apple silicon running macOS 26, the same requirements as the container tool generally.⁵ The tool is open source on GitHub, written in Swift.⁵

Does upgrading to 1.0 break anything?

One thing: system configuration moves from UserDefaults-backed properties to a TOML file at ~/.config/container/config.toml, and the container system property get/set subcommands are removed.² The 1.0 release notes link a tutorial for the migration.² The version 0 XPC API compatibility is also removed, which matters if you built clients against the API.²

Container machines slot into the same story this WWDC kept telling: the Mac as a serious home for cross-platform and agentic development. Running Agentic AI on the Mac with MLX covers the model-serving half of that story, and What’s New in Swift (2026) covers the language work that makes Swift-on-Linux a first-class target. The full series hub is the Apple Ecosystem Series.

References