Installation
This page takes you from nothing to a working Linux build. Plan on about ten minutes, most of it waiting for the first image download.
Before you start
You need:
- an Apple silicon Mac,
- a
nix-darwinconfiguration managed with flakes, and - Apple's
containertool, installed and running (covered in step 1).
1. Install Apple's container
HexBox doesn't install container for you, so you can use whichever
installer you prefer. Pick one:
# Homebrew
brew install container
# mise (install it globally; see the note below)
mise use -g container
# Apple's signed package, from https://github.com/apple/container/releases
gh release download --repo apple/container --pattern 'container-*-installer-signed.pkg'
sudo installer -pkg container-*-installer-signed.pkg -target /
Then start it:
container system start
HexBox looks for container on your PATH. Background processes such as the
Nix daemon have a much shorter PATH, so HexBox also checks
/opt/homebrew/bin, /usr/local/bin, and your mise shims.
If you use mise, install container globally, as above. A version that's only
set for one project directory is invisible to the Nix daemon. If you really
want a per-project version, set
containerBinary to the full path that
mise which container prints.
2. Add HexBox to your flake
Add the input and the module, and turn the builder on:
{
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 gets 4 CPUs and only 1 GB of memory unless you say otherwise. 8 GB is a sensible starting point; see Configuration for sizing advice.
3. Switch
sudo darwin-rebuild switch --flake .#my-host
The first switch also creates the builder's SSH keys: the key Nix logs in
with, the builder's own host key, and a known_hosts file so your Mac can
check it's talking to the right machine.
If container can't be found, the switch still finishes, but prints
error: Apple container is not installed. Fix that before going on.
4. Start the builder and try a build
hb builder repair
hb builder test
hb builder repair creates the machine. The first time, it downloads the
builder image, so give it a few minutes. When it finishes, it prints
Run hb builder test to verify remote builds.
hb builder test then builds a tiny Linux package through the builder. You
should see a line like this:
building '/nix/store/…-hexbox-builder-smoke.drv' on 'ssh-ng://builder@container-builder'...
That's it. From now on, any aarch64-linux build goes to the builder
automatically, and the machine starts and stops on its own.