macOS Container Machines

Container machine provides a highly integrated Linux environment that works seamlessly on your Mac. Container machines are fast, lightweight and persistent. They are based on standard OCI images that can be built and shared. Host integrations such as automatic user and home directory sharing provide quick and easy access to your Linux environment no matter where you are in a terminal.

Container machine 提供了一个高度集成的 Linux 环境，可以在你的 Mac 上无缝运行。Container machine 快速、轻量且持久。它们基于标准的 OCI 镜像，可以进行构建和共享。诸如自动用户和主目录共享等主机集成功能，无论你在终端的哪个位置，都能让你快速、轻松地访问 Linux 环境。

Why container machines

为什么选择 Container machines

Containers are typically modeled after an application. A container machine is modeled after a Linux environment. It runs the image’s init system allowing you to register long running services or test your application under a process supervisor. A container machine automatically maps your username and home directory into the Linux environment. Your repositories and dotfiles are available on both platforms.

容器通常以应用程序为模型，而 Container machine 则以 Linux 环境为模型。它运行镜像的 init 系统，允许你注册长期运行的服务，或在进程管理器下测试你的应用程序。Container machine 会自动将你的用户名和主目录映射到 Linux 环境中，使你的代码仓库和配置文件在两个平台上都能使用。

Use editors and tools directly on macOS simultaneously building and running your application inside of the Linux environment. Edit on the Mac, build inside. Your repo lives in $HOME on macOS and is mounted at /Users/ inside the container machine. Use your macOS editor or IDE; compile and run inside your container machine.

你可以直接在 macOS 上使用编辑器和工具，同时在 Linux 环境内构建和运行应用程序。在 Mac 上编辑，在内部构建。你的代码仓库位于 macOS 的 $HOME 目录下，并被挂载到 Container machine 内部的 /Users/。你可以使用 macOS 的编辑器或 IDE，并在 Container machine 内部进行编译和运行。

Use macOS-native tooling against Linux artifacts. Profilers, screenshot tools, browsers, and GUI debuggers on your Mac all see the same files the container machine sees — there is no copy step between “I built it” and “I am inspecting it”.

使用 macOS 原生工具处理 Linux 构建产物。你 Mac 上的性能分析器、截图工具、浏览器和 GUI 调试器都能看到与 Container machine 相同的文件——在“构建完成”和“检查产物”之间无需任何复制步骤。

Real Linux services for testing. Run a database or whatever your stack needs as a system service — systemctl start postgresql works on images with systemd installed.

用于测试的真实 Linux 服务。你可以将数据库或技术栈所需的任何组件作为系统服务运行——在安装了 systemd 的镜像上，systemctl start postgresql 可以直接工作。

One environment per target distro. Create as many container machines as you have target distros — alpine, ubuntu, debian. Each has the same $HOME and the same dotfiles from your Mac. Quickly test your application in various distributions.

每个目标发行版对应一个环境。你可以根据需要创建任意数量的 Container machine（如 alpine、ubuntu、debian）。每个环境都拥有相同的 $HOME 和来自你 Mac 的相同配置文件，方便你快速在不同发行版中测试应用程序。

Quickstart

快速入门

container machine create alpine:latest --name dev
container machine run -n dev whoami # your host username, not root
container machine run -n dev pwd # /home/<you> — your Mac home dir, mounted in
container machine run -n dev # interactive shell; cd into your repos in $HOME

container machine run is how you get a shell or run a single command. If the container machine is stopped, run boots it first.

container machine run 是你获取 shell 或运行单个命令的方式。如果 Container machine 已停止，run 命令会先将其启动。

Working in a container machine

在 Container machine 中工作

Open a shell, or run a single command. With no command, container machine run opens an interactive shell as a user that matches your host account: 打开 shell 或运行单个命令。如果不带命令，container machine run 会以与你主机账户匹配的用户身份打开交互式 shell：

container machine run -n dev

Pass a command to run it once and exit: 传入命令以运行一次并退出：

container machine run -n dev uname -a
container machine run -n dev -- cat /proc/cpuinfo

Set a default. Pick a default container machine so you can drop the -n flag: 设置默认值。选择一个默认的 Container machine，这样就可以省略 -n 参数：

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

List, inspect, stop, delete: 列出、检查、停止、删除：

container machine ls # list all container machines
container machine inspect dev # JSON detail for one
container machine stop dev # stop the container machine
container machine rm dev # delete, including its persistent storage

container machine has the alias m, so m ls, m run, etc. all work. container machine 有别名 m，因此 m ls、m run 等命令均可使用。

Resize CPUs, memory, or change the home-mount

调整 CPU、内存或更改主目录挂载

container machine set updates configuration on disk. Changes take effect after the next stop and start: container machine set 会更新磁盘上的配置。更改将在下次停止并启动后生效：

container machine set -n dev cpus=4 memory=8G
container machine stop dev
container machine run -n dev -- nproc

Memory defaults to half of host memory. The home-mount can be rw (default), ro, or none. 内存默认为主机内存的一半。主目录挂载可以是 rw（默认）、ro 或 none。

Bring your own container machine image

使用你自己的 Container machine 镜像

Any Linux image that includes /sbin/init works as a container machine. For example, this Dockerfile builds an Ubuntu 24.04 container machine image with systemd and common command-line tools: 任何包含 /sbin/init 的 Linux 镜像都可以作为 Container machine 使用。例如，以下 Dockerfile 构建了一个带有 systemd 和常用命令行工具的 Ubuntu 24.04 Container machine 镜像：

FROM ubuntu:24.04
ENV container container
RUN apt-get update && \
    apt-get install -y \
    dbus systemd openssh-server net-tools iproute2 iputils-ping curl wget vim-tiny man sudo && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* && \
    yes | unminimize
RUN >/etc/machine-id
RUN >/var/lib/dbus/machine-id
RUN systemctl set-default multi-user.target
RUN systemctl mask \
    dev-hugepages.mount \
    sys-fs-fuse-connections.mount \
    systemd-update-utmp.service \
    systemd-tmpfiles-setup.service \
    console-getty.service
RUN systemctl disable \
    networkd-dispatcher.service
RUN sed -i -e 's/^AcceptEnv LANG LC_\*$/#AcceptEnv LANG LC_*/' /etc/ssh/sshd_config

Build it and create a container machine from it: 构建它并从中创建一个 Container machine：

container build -t local/ubuntu-machine:latest .
container machine create local/ubuntu-machine:latest --name ubuntu

By default, container runs a built-in setup script on first boot to provision the user described above. To use your own setup instead, add an executable script at /etc/machine/create-user.sh to the image. It runs once, as root, on first boot, with these variables set: CONTAINER_GID, CONTAINER_HOME, CONTAINER_MACHINE_ID, CONTAINER_UID, CONTAINER_USER.

默认情况下，container 在首次启动时会运行一个内置的设置脚本来配置上述用户。若要使用你自己的设置，请在镜像中添加一个位于 /etc/machine/create-user.sh 的可执行脚本。它会在首次启动时以 root 身份运行一次，并设置以下变量：CONTAINER_GID、CONTAINER_HOME、CONTAINER_MACHINE_ID、CONTAINER_UID、CONTAINER_USER。