Discover container machines

Watch on Apple Developer

TL;DR

What Container machine provides

Container machine is a new feature built on top of Containerization, Apple's Swift framework for running Linux containers on macOS. It provides a lightweight Linux environment that is fast like a container but persistent like a virtual machine.

The goal is cross-platform development with minimal context switching: developers can edit and use macOS tools while building, running, and testing inside Linux.

• Runs each Container machine inside its own lightweight virtual machine.
• Uses the same OCI image format as containers.
• Persists changes made inside the environment across sessions.
• Integrates with the existing container command-line tool.

Containerization foundation

Containerization supplies APIs for storage, networking, execution, and a Linux init system. It is designed around VM-based isolation for each container while preserving lightweight behavior and sub-second startup characteristics.

The companion container tool provides commands for image creation, distribution, and lifecycle management. Container machine extends that tool with a Linux environment that can be created, run, stopped, and revisited.

• For architecture background, see the related WWDC 2025 session "Meet Containerization."
• The open-source resources are Apple's container and containerization GitHub projects.

Design principles

Container machine was shaped around four practical requirements: fast and lightweight operation, simple management, persistence, and seamless integration with macOS.

The persistence model lets a project-specific Linux environment accumulate tools and dependencies over time, while quick creation makes it reasonable to use separate machines for separate projects or toolchains.

• Fast and lightweight enough to fit existing development workflows.
• Simple to create and operate from the CLI.
• Stateful, so installed tools and project changes remain available later.
• Integrated with macOS to reduce switching between host and Linux environments.

Creating and running a machine

The container machine command exposes subcommands such as create, run, and stop. A new machine can be created from an OCI image and set as the default so subsequent commands do not need to repeat its name.

Running commands through the machine executes them in Linux. For example, uname prints Linux inside the machine, while macOS would report Darwin.

• Use container machine create with a name and image to create an environment.
• Use container machine run <command> to execute a command inside the default machine.
• Use container machine run with no command to start an interactive shell.

Inspect Container machine commands

Shows available Container machine actions, including commands such as create, run, and stop.

container machine

Create an Alpine-based default machine

Creates a machine named demo, sets it as the default machine on the Mac, and uses the Alpine OCI image as the starting point.

container machine create --name demo --set-default alpine

Run commands inside Linux

Runs a one-off command, checks the Linux runtime with uname, and starts an interactive shell when no command is supplied.

container machine run echo hi
container machine run uname
container machine run

macOS integration and project workflow

Container machine automatically mirrors the macOS username and current working directory inside the Linux environment. Combined with filesystem sharing, this makes project files edited on macOS immediately available inside the machine.

The demo uses a Vapor web server project: files are edited in Xcode, assets are edited in Icon Composer, the app is built and run in Linux with Swift, and the running server is tested from Safari on macOS.

Because the machine has an isolated network, the demo lists machines to find the machine IP address and configures Vapor to listen on that external interface so Safari can connect to the server.

• container machine list displays machine names, IP addresses, and resource information.
• Shared project files avoid manual copying between macOS and Linux.
• For host-browser testing, configure the server to listen on the Container machine IP and the expected port, such as 8080 in the demo.

List machines and enter the environment

Lists Container machines to obtain details such as IP address, then opens an interactive Linux shell.

container machine list
container machine run

Build and run the Swift server in Linux

Compiles and runs the Vapor application from inside the Container machine using the installed Swift toolchain.

swift run

Resources

• Container
• Containerization

Related Sessions

• Meet Containerization

Unofficial, not associated with Apple. By