HexBox
Hex the platypus, in devil horns, packing source files into Git and Helix packages inside a glass display case.

A Linux builder that lives in a box on your Mac.

HexBox is a nix-darwin module. Turn it on, and Nix on your Mac can build Linux packages, without a server or a VM to babysit.

Habitat
An Apple container machine on your Mac
Diet
aarch64-linux derivations, fed by Nix
Habits
Up in seconds when a build arrives. Naps when the work dries up.
Memory
Long. His /nix store survives every nap.
Dislikes
x86_64, Intel Macs
inputs.hexbox.url = "github:RobertDeRose/nix-hex-box";

What it takes care of

The plumbing
HexBox writes nix.buildMachines, SSH aliases, keys, and a known_hosts file that pins the builder’s host key. Linux derivations go to the box with nothing else to configure.
Waking and sleeping
The first SSH connection boots the machine. Five minutes after the last one closes, the guest powers off. You never start or stop it yourself.
Your choice of container
Install Apple’s container from Homebrew, mise, or Apple’s package. HexBox finds it, even from the root nix-daemon.
A small, current image
The builder runs Alpine with OpenSSH and Lix, rebuilt weekly for security fixes. Point imageContainerfile at your own Containerfile to use a custom one.
Your containers can reach your Mac
By default, Apple containers resolve host.container.internal to services on your Mac.
Telling you what’s wrong
The hb helper checks the runtime, machine, SSH, and store, repairs what it can, and runs a real build to prove it works.

How a build gets to the box

Nix sees an ordinary ssh-ng remote builder. HexBox makes sure something is always ready to answer.

  1. Nix asks for Linux. A derivation needs aarch64-linux, so the nix-daemon picks the container-builder machine.
  2. SSH knocks. Its ProxyCommand switches from root to you, because you own the container runtime.
  3. The box wakes. If nix-builder is asleep, the proxy boots it and waits for its SSH server to answer.
  4. The build runs inside. socat relays to the guest’s sshd, and its nix-daemon does the work.
  5. Results come home. Outputs are copied back into your Mac’s store, ready to use.
  6. The box naps. With no connections left, it powers off after the idle timeout.

Install

  1. Get Apple’s container

    Homebrew

    brew install container
    container system start

    mise

    mise use -g container
    container system start

    Install it globally. A per-project install is invisible to the root nix-daemon; for one of those, set containerBinary to what mise which container prints.

    Apple’s package

    gh release download --repo apple/container --pattern 'container-*-installer-signed.pkg'
    sudo installer -pkg container-*-installer-signed.pkg -target /
    container system start
  2. Add HexBox to your flake

    {
      inputs.hexbox.url = "github:RobertDeRose/nix-hex-box";
    
      outputs = inputs: {
        darwinConfigurations.my-host = inputs.darwin.lib.darwinSystem {
          system = "aarch64-darwin";
          modules = [
            inputs.hexbox.darwinModules.default
            {
              services.container-builder = {
                enable = true;
                memory = "8G";
              };
            }
          ];
        };
      };
    }

    The machine defaults to 4 CPUs and 1 GB of memory. Give it more for anything bigger than small packages.

  3. Switch, then try a build

    sudo darwin-rebuild switch --flake .#my-host
    hb builder repair
    hb builder test

    The switch creates the builder’s SSH keys. The first hb builder repair downloads the image and creates the machine, so it takes a few minutes. After that, the box wakes in seconds.

A good fit if you

  • Manage your Mac with nix-darwin and build for aarch64-linux.
  • Already use Apple’s container, or don’t mind installing it.
  • Want a builder that costs nothing while you aren’t building.

Not a fit if you

  • Need x86_64-linux builds. The box is always aarch64-linux.
  • Use an Intel Mac, or don’t use nix-darwin.
  • Run NixOS VM tests on an M1 or M2. Without nested virtualization they run under emulation, and slowly.