Skip to main content

Options

All options live under services.container-builder. For the settings most people change, and why, see Configuration.

The basics​

OptionDefaultWhat it does
enablefalseTurns the builder on.
useryour nix-darwin primary userThe macOS user who owns the container runtime and the builder.
containerBinary"container"The container command to run. A bare name is looked up on your PATH, then in /opt/homebrew/bin, /usr/local/bin, and your mise shims; a full path is used as-is.
cli.completions.enablefalseInstalls bash, zsh, and fish completions for hb.

The machine​

OptionDefaultWhat it does
cpus4CPUs for the builder machine.
memory"1G"Memory for the builder machine, for example "8G".
homeMount"none"Whether the builder can see your home folder: "none", "ro" (read-only), or "rw".
containerName"nix-builder"The machine's name in Apple container.
idleShutdown.enabletrueShuts the builder down when no one is connected.
idleShutdown.timeoutSeconds300How long the builder waits, with no connections, before shutting down.

The image​

OptionDefaultWhat it does
imageRepository"ghcr.io/robertderose/nix-hex-box/hexbox-builder"Where the builder image comes from.
nixVersion"latest"The image tag. Despite the name, it's the tag of the builder image, not a Nix version. Change it to pin an image, or to rebuild a custom one.
imageContainerfilenullA Containerfile to build your own image from. The image must include socat, base64, getent, and a working /sbin/init.
imageBuildContextnullAn absolute path to a folder your Containerfile can copy files from. Without it, the build has an empty context.

Changing any of these replaces the builder machine, which empties its /nix store.

How Nix uses the builder​

These end up in nix.buildMachines.

OptionDefaultWhat it does
maxJobs4How many builds Nix runs on the builder at once. On M1 and M2 Macs, use 1 or 2.
speedFactor1How strongly Nix prefers this builder over others you have.
systems[ "aarch64-linux" ]What the builder can build.
supportedFeatures[ "benchmark" "big-parallel" "kvm" "nixos-test" ]Build features the builder offers.
mandatoryFeatures[ ]Features a build must ask for to be sent to this builder.
protocol"ssh-ng"The remote store protocol Nix uses.

SSH and networking​

OptionDefaultWhat it does
hostAlias"container-builder"The SSH host name Nix uses for the builder.
sshUser"builder"The user Nix logs in as inside the builder.
containerPort22The SSH port inside the builder.
exposeHostContainerInternaltrueLets Apple containers reach your Mac at host.container.internal.
readiness.timeoutSeconds60How long each SSH readiness check waits for a login to succeed. hb builder reset runs one check; hb builder repair retries up to three times.
readiness.intervalSeconds1How often they try.

Files​

OptionDefaultWhat it does
workingDirectory"~/.local/state/hb"Where HexBox keeps its keys, scripts, and logs. See Files HexBox manages.

Removed options​

The installer.* and socktainer.* options were removed when HexBox stopped installing Apple container and managing Socktainer. Setting any of them stops your configuration from building, with a message saying what to do instead.