goldboot: golden images for real hardware, built from a declarative config

The problem: every machine drifts away from the one you set up

The README opens with a description of something everyone recognises. People usually do not reinstall their operating system from scratch very often, and when they do, chaos ensues the moment they reach that pristine desktop or terminal. Settings get changed, applications are installed, bloatware is removed, and files are downloaded here and there, and the system is generally altered from its original state into a new customized state by a manual flurry of mouse clicks and key presses. The README compares this to mutable infrastructure, where you mutate the state of your system repeatedly until it suits your needs, and when something goes awry you have to make the necessary changes to get it back in line. The payoff of that approach disappears when something major breaks or you have to migrate to a new computer, because you end up starting over and reapplying your changes again, probably slightly differently. The primary language is Rust, the licence is the Unlicense, the default branch is master, and the last push was on 2026-09-07 with recent tags at goldboot-v0.0.10 and goldboot-image-v0.0.5 from 2025-03-04.

nix-shell -p goldboot

That is one of the install routes, and the README lists several, which is worth reading because the choice of route shapes how you will run it in CI.

The goldboot approach: a config file becomes a deployable image

The alternative the README describes is immutable infrastructure, where every boot starts the system in almost the same state and changes made during runtime vanish on reboot. The README concedes that this approach has real benefits but requires quite a bit of effort from the user. goldboot is offered as a tool that builds machine images for real hardware and helps you get close to that without doing all the work yourself. The mechanism is a declarative configuration file for each machine you want to deploy, and using that configuration goldboot builds an image either on your local machine or on a CI platform like GitHub Actions. The resulting image can then be deployed to real hardware via a USB drive or through PXE boot. And like Docker images, goldboot images can be stored in a registry and pulled onto real hardware.

alias goldboot="docker run --rm -v .:/root fossable/goldboot"

That alias is the Docker install route, and it doubles as the shape of a CI step, since the tool is invoked against the directory holding the configuration.

How it compares to docker and packer

The README puts the comparison itself in one sentence: goldboot is approximately what you would get if docker and packer were mixed together, except that instead of building containers or virtual machines, goldboot builds images for real hardware. The definition of a golden image follows: machine images, also known as golden images, that contain your operating system or systems, applications, software patches and configuration all rolled into one easily deployable package. The analogy is exact in one respect and approximate in another, and the approximate part is the interesting bit. A container image and a virtual machine image are both products of a build running in a controlled environment, and a golden image is the same idea applied to a disk image for a physical machine. The difference is that a container runtime is designed to deliver the image on any host, while a goldboot image is tied to the hardware and firmware it was built for, which is why the README mentions PXE boot and a USB drive as the delivery paths rather than a registry pull alone.

Four install routes, and a warning to read first

The installation section is a set of collapsed blocks, one per distribution channel, and the set is wide for a project at 0.0.x. Docker is installed as an alias over the fossable/goldboot image with the current directory mounted at /root. crates.io is a plain cargo install goldboot. The AUR route downloads a snapshot tarball into /tmp, extracts it and runs makepkg -si. Nixpkgs is a one line nix-shell invocation. And a manual route downloads a release binary from GitHub releases with curl and chmods it into /usr/bin, with a dependencies step that installs libudev1, libgtk-4-1 and libglib2.0-0 through apt-get. Above all of that sits a warning in bold in the README: the tool is totally unfinshed and should be used for testing only, proceed at your own risk. That is the first thing a reader should see, and it is the honest summary of a 0.0.x project whose most recent release was in March 2025.

apt-get install -y libudev1 libgtk-4-1 libglib2.0-0

Those three libraries are the runtime dependencies of the manual build, which tells you the tool is not a pure command line binary in the way a packer plugin might be, since it links against a GUI stack.

Building images inside a GitHub Actions workflow

Because the README's premise is that building golden images with CI is common practice, there is a GitHub action to make it easy, and the workflow example is short enough to read as the recommended integration. The action checks out the repository, builds the image from a config path with the fossable/goldboot-action, and uploads the resulting image as an artifact.

steps:
  - name: Checkout
    uses: actions/checkout@v4

  - name: Build goldboot image
    uses: fossable/goldboot-action@main
    with:
      config-path: goldboot.json
      output-path: image.gb

  - name: Save image artifact
    uses: actions/upload-artifact@v3
    with:
      name: my_image.gb
      path: image.gb

The config is a goldboot.json file and the output is an image.gb file, and the artifact step is what makes the image travel to the next job or to a machine. The action is referenced by the main branch, which is a detail worth noting for anyone pinning versions in production.

The workspace layout, and what the examples tell you

The repository is a Cargo workspace with four members: goldboot itself, goldboot-image, goldboot-macros and goldboot-registry, using resolver 3 and a release profile with strip enabled. The macro and registry crates are the interesting part of that list, because a macro crate implies the configuration format is expressed in Rust types rather than in a loose schema, and a registry crate implies the tool knows about a catalogue of what it can build, which lines up with the README's statement that goldboot images can be stored in a registry and pulled onto real hardware. The workspace dependencies are modest and specific, with serde and serde_derive, sha2 for hashing, hex, rand, regex, strum for enum handling, tracing for logs, zstd for compression, reqwest for HTTP, and a crate called roniker, along with the fossable namespace package. The examples live in a separate repository, goldboot-examples, which contains example configurations of all supported OS types and system architectures and is built on a weekly schedule against the latest version of goldboot, and the README's table shows the breadth: Alpine and Arch Linux on x86_64, Windows 10 on x86_64 and macOS on x86_64.

[workspace]
members = [
  "goldboot",
  "goldboot-image",
  "goldboot-macros",
  "goldboot-registry",
]
resolver = "3"

The weekly rebuild of the examples is the closest thing in the documentation to a health signal, since it proves the configuration format still compiles against the current release every week.

The limits, and what to compare it against

Three things bound the ambition here. The first is the warning itself, that the tool is unfinished and for testing only, which is not a small caveat for something that writes disk images. The second is that the deliverable is tied to hardware, so a golden image built for one machine configuration is not portable the way a container image is, and a fleet of heterogeneous machines needs several images. The third is the version maturity, since the tags sit at 0.0.10 and the manual install instructions in the README still point at goldboot-v0.0.7, which is a sign that the documentation and the releases have drifted apart. The alternative to weigh is the plain approach of writing an Ansible, Chef or Puppet playbook, and the topic list names all three, which tells you they are the intended comparison. The difference in approach is that a configuration management tool converges the live machine to the desired state every run, and reports drift, while goldboot captures a one-off image and clones it, which is faster to deploy across a fleet and has no agent on the target. The price of that speed is that any change after the image was built is a new image, and the target machine keeps whatever it was given.

Editorial conclusion

Adopt goldboot if you provision many identical physical machines and want the configuration of each one captured in a versioned file that CI can turn into an image, because the golden image model is the piece docker and packer give you only for containers and virtual machines. Do not adopt it for production, since the README states plainly that the tool is unfinished and should be used for testing only, at your own risk. Before you evaluate it further, read the examples repository for the configurations of each supported OS and architecture, and check the release you are considering, because the current tags are in the 0.0.x range and the manual install instructions still point at an older version.

Frequently asked questions

Official sources

1. cilki/goldboot on GitHub
2. License: Unlicense
3. Project website
4. README
5. Releases