From ede16056bcba3bd54d5acda1106d644b83b21c6a Mon Sep 17 00:00:00 2001 From: Andrew Barnes Date: Sat, 13 Jun 2026 09:05:01 -0400 Subject: [PATCH 1/2] docs: clarify container machine vs container semantics --- docs/container-machine.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/container-machine.md b/docs/container-machine.md index 2514c99fa..97ccd08cc 100644 --- a/docs/container-machine.md +++ b/docs/container-machine.md @@ -4,8 +4,8 @@ Container machine provides a highly integrated Linux environment that works seam ## Why 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. Use editors and tools directly on macOS simultaneously building and running your application inside of the Linux environment. +Containers are typically modeled after an application or task. A container machine is a convenience wrapper around a Linux environment: it pairs a standard OCI image with dedicated persistent root storage, boots the image's init system, and adds host integrations such as automatic user and home directory sharing. +Both regular containers and container machines keep their changes until you delete them, but container machines are optimized for long-lived, reusable Linux environments instead of single-application workloads. Your repositories and dotfiles are available on both platforms, so you can use editors and tools directly on macOS while simultaneously building and running your application inside 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. - **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". From 7951ed8d87071214b9a72c275d104687203e6864 Mon Sep 17 00:00:00 2001 From: Andrew Barnes Date: Mon, 15 Jun 2026 23:19:16 -0400 Subject: [PATCH 2/2] docs: tighten container machine wording --- docs/container-machine.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/container-machine.md b/docs/container-machine.md index 97ccd08cc..81d79f936 100644 --- a/docs/container-machine.md +++ b/docs/container-machine.md @@ -4,8 +4,8 @@ Container machine provides a highly integrated Linux environment that works seam ## Why container machines -Containers are typically modeled after an application or task. A container machine is a convenience wrapper around a Linux environment: it pairs a standard OCI image with dedicated persistent root storage, boots the image's init system, and adds host integrations such as automatic user and home directory sharing. -Both regular containers and container machines keep their changes until you delete them, but container machines are optimized for long-lived, reusable Linux environments instead of single-application workloads. Your repositories and dotfiles are available on both platforms, so you can use editors and tools directly on macOS while simultaneously building and running your application inside the Linux environment. +Containers are typically modeled after an application or task. A container machine uses a standard OCI image to provide a long-lived Linux environment with host integrations such as automatic user and home directory sharing. +Both regular containers and container machines keep their changes until you delete them, but container machines are organized around reusable Linux environments rather than single-application workloads. Your repositories and dotfiles are available on both platforms, so you can use editors and tools directly on macOS while simultaneously building and running your application inside 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. - **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".