Skip to main content

Configuration

Every setting lives under services.container-builder. Only enable is required; everything else has a default. This page covers the settings most people change. Options lists all of them.

Machine size​

services.container-builder = {
enable = true;
cpus = 4; # the default
memory = "8G"; # the default is "1G"
maxJobs = 4; # the default
};

cpus and memory size the builder machine. The 1 GB default is enough for small packages, but compilers and linkers run out of memory quickly, so most people want 4 to 8 GB or more. The memory is only in use while the machine is running.

maxJobs is how many builds Nix runs on the builder at once. Keep it at or below cpus.

On M1 and M2 Macs, keep maxJobs low​

The builder advertises the kvm and nixos-test features, so Nix sends NixOS VM tests to it. Macs before the M3 can't run virtual machines inside virtual machines, so those tests fall back to slow software emulation. Each one needs a full CPU and about 1 GB of memory, and running several at once makes them time out or crashes the builder's Nix daemon.

On those Macs, set maxJobs to 1 or 2. The builder logs /dev/kvm is unavailable when this applies to you.

When it shuts down​

The builder powers off once no one has been connected to it for five minutes. To wait longer, or never shut down:

services.container-builder.idleShutdown.timeoutSeconds = 1800; # 30 minutes
# or
services.container-builder.idleShutdown.enable = false;

The builder checks every 30 seconds, so it may run up to half a minute past the timeout. Shutting down doesn't lose anything: the /nix store is kept.

Access to your home folder​

By default, the builder can't see any of your files. Nix copies everything a build needs, so most people never need to change this. If you have a reason to let the builder read your home folder, or write to it:

services.container-builder.homeMount = "ro"; # read-only; "rw" allows writes

Using your own builder image​

By default, the builder runs an image published by this project: ghcr.io/robertderose/nix-hex-box/hexbox-builder:latest. It's Alpine Linux with OpenSSH, sudo, and Lix, and it's rebuilt weekly to pick up security fixes. If you'd rather pin a version, the image is also published under tags such as alpine-3.22-lix-2.95.2-2; set nixVersion to the tag you want.

To build your own image instead, point HexBox at a Containerfile:

services.container-builder = {
imageContainerfile = ./builder.Containerfile;
# Optional: a folder the build can COPY files from. It must be an absolute path.
imageBuildContext = "/Users/me/builder-image";
};

HexBox builds it the first time the builder starts. Your image needs socat, base64, getent, and a working /sbin/init, because HexBox uses them to set up the machine and to relay SSH into it.

HexBox only rebuilds the image when its tag is missing. After changing your Containerfile, change nixVersion too, or delete the old image, so the new one gets built.

Changing the image recreates the builder machine, which empties its /nix store. The next builds will download or rebuild what they need.

Shell completions for hb​

services.container-builder.cli.completions.enable = true;

This installs completions for bash, zsh, and fish where your shell already looks for them. HexBox doesn't change your shell's startup files.

Running as a different user​

The builder machine belongs to one macOS user, who owns the container runtime. That's your nix-darwin primary user unless you set user:

services.container-builder.user = "alex";