LinuxMachine

Create and use persistent Linux machines with Apple Container.

LinuxMachine separates distribution-independent machine management from small distribution adapters. It provides:

• a persistent Linux root filesystem that survives stops and restarts;
• read-write access to the macOS Home directory;
• matching macOS username and current directory inside the machine;
• outbound networking and DNS through Apple Container;
• simple user and root shell commands;
• an included Debian 13 adapter as the first supported distribution.

Initial setup

1. Install Apple Container

./install-apple-container.sh

The script downloads the signed Apple Container 1.2.0 installer from the official GitHub release, verifies the package signature, and opens the standard macOS Installer. Return to Terminal after the installation is complete.

2. Set up a distribution

The included Debian 13 adapter can be run with:

./setup-debian-machine.sh

It creates a machine named debian13 with 4 CPUs, 4 GiB of RAM, and read-write access to $HOME.

Resources can be changed during creation:

MACHINE_CPUS=8 MACHINE_MEMORY=8G ./setup-debian-machine.sh

Running a distribution setup script again is safe: an existing named machine is selected as the default but is not deleted or recreated.

Architecture

The distribution-independent scripts are:

• install-apple-container.sh, which installs Apple Container;
• setup-linux-machine.sh, which validates resources, builds an image, and creates a persistent machine;
• machine.sh, which opens shells and manages the default machine.

Distribution-specific files are isolated:

• setup-debian-machine.sh defines the Debian 13 machine and checks it;
• images/debian-13/Dockerfile defines the Debian 13 system image and packages.

A distribution adapter supplies MACHINE_NAME, MACHINE_IMAGE, and MACHINE_BUILD_CONTEXT, then calls setup-linux-machine.sh. This keeps the shared machine lifecycle independent of Debian, Ubuntu, Alpine, or any other Linux distribution.

Everyday use

Open a user shell:

./machine.sh

If only one machine exists, machine.sh selects it automatically. With multiple machines, it uses the default Apple Container machine unless MACHINE_NAME is set.

Open a root shell:

./machine.sh root

Run a single command:

./machine.sh run uname -a
./machine.sh root id

Manage the machine:

./machine.sh status
./machine.sh inspect
./machine.sh stop
./machine.sh logs

status prints a compact table of all machines. inspect prints full details for the explicitly selected, sole, or default machine.

To target a named machine instead of the default:

MACHINE_NAME=my-machine ./machine.sh
MACHINE_NAME=my-machine ./machine.sh root
MACHINE_NAME=my-machine ./machine.sh inspect

The included Debian adapter also shows how to install machine.sh into ~/.local/bin. If that directory is in $PATH, the command can be used from any macOS directory. Apple Container Machine automatically opens the corresponding directory from the mounted macOS $HOME.

Generic machine configuration

setup-linux-machine.sh uses these environment variables:

MACHINE_NAME=my-machine
MACHINE_IMAGE=local/my-machine:latest
MACHINE_BUILD_CONTEXT=/path/to/build-context
MACHINE_CPUS=4
MACHINE_MEMORY=4G

The first three variables are required. CPU and memory have the defaults shown above. The macOS Home directory is always mounted with read-write access.

Persistence and deletion

Stopping a machine does not remove its filesystem. Installed packages and changes under /etc, /usr, and /var remain available after the next start. Files under the mounted Home directory remain on macOS.

Machine deletion is intentionally not automated because it destroys the persistent Linux filesystem:

container machine delete my-machine

This command does not delete files in the mounted macOS $HOME.

License

LinuxMachine is available under the MIT License.