gokrazy: turn a Go program into a Raspberry Pi or x86 appliance

The problem gokrazy removes rather than manages

The README states the motivation plainly: the authors were unhappy about tracking security issues and doing Linux distribution maintenance across a set of Raspberry Pis. Their question was whether they could drop memory-unsafe languages and everything not strictly needed. gokrazy is the answer to that question, which makes it a different kind of project from a normal Linux image builder. It is not trying to make distribution maintenance easier. It is trying to make maintenance unnecessary by not shipping a distribution.

The audience follows from that. If you write Go, cross-compile it, and deploy it to a small board or a PC that does one job, you are the target user. The supported target list in the project description covers Raspberry Pi 3, Pi 4, Pi 5, Pi Zero 2 W, and PCs on x86_64 or ARM64. That is a deliberately narrow hardware set, and it is worth reading as a statement of scope rather than a roadmap.

What you give up in exchange is the ability to install things. There is no apt, no dnf, no shell session where you fix a problem at 2am. The system is the appliance. If your workload can be expressed as one or more Go programs plus a kernel, this trade is favourable. If it cannot, no amount of configuration will make it fit.

How the repository is split: system code versus image tooling

The most useful thing to understand about gokrazy is that the repository you are reading is not the thing that builds your SD card. The README's repository structure section separates github.com/gokrazy/gokrazy, described as system code, the main issue tracker and documentation, from github.com/gokrazy/tools, described as the SD card image creation code.

The tools module pulls in four further repositories: gokrazy/firmware for Raspberry Pi 3 or 4 firmware files, gokrazy/rpi-eeprom for Raspberry Pi 4 EEPROM files, gokrazy/rpi5-eeprom for Raspberry Pi 5 EEPROM files, and gokrazy/kernel for a pre-built kernel image and bootloader config. So the boot chain is assembled from pinned upstream artifacts rather than built from source on your machine. That is a real design decision: it makes image creation fast and reproducible, and it means kernel and firmware updates arrive when those repositories are updated.

The top-level file list of the system repository reads like the responsibilities of a tiny init and supervision layer: supervise.go, mount.go, mountext4.go, netlink.go, listeners.go, status.go, update.go, reboot.go, powerbutton.go, signals.go, httpsredirect.go, xsrf.go, machineid.go, modules.go, sbom.go. Alongside those sit directories for cmd, internal, integration, ifaddr and empty. The presence of update.go and reboot.go at the top level is the clearest signal that updates are handled by the running system itself rather than by an external agent.

One detail worth flagging: the repository's primary language is listed as JavaScript, which reflects the Hugo-based website under website/ rather than the system code. The go.mod file declares Go 1.26 and a dependency set that is small and mostly low-level networking and device access: mdlayher/packet, vishvananda/netlink, rtr7/dhcp4, mdlayher/watchdog, kenshaw/evdev, beevik/ntp, google/gopacket. There is no web framework and no configuration library in that list.

Installing the tooling and building a first image

The README does not contain install or usage steps for the image builder. It points at gokrazy.org for the documentation and describes the repository structure. The commands below come from the README's documentation section, which covers the website only, not the device workflow. Treat the website as the place to get the actual build instructions.

What the README does show is how the documentation site itself is built. The website subdirectory is Hugo's root directory, so you change into it before running anything. To preview the docs locally, the README gives this command:

hugo serve

That starts Hugo's development server and serves the site from the website directory, which is what you would use if you wanted to read the documentation offline or check a docs change. To generate the static site instead, the README gives:

hugo

The README states that the generated content lands in the ./docs directory and adds an explicit warning: do not update anything there manually. That is the one build instruction the repository itself provides.

For the part that matters to a device, the README's only concrete direction is the link to gokrazy.org and the platforms page. Before you run anything, confirm on that platforms page that your board is listed, and check the tools repository for how the image creation code is meant to be obtained for your Go toolchain. The go.mod in this repository pins github.com/gokrazy/internal and github.com/anatol/vmtest, which suggests the integration tests exercise images in a VM, but the README does not document a command for that.

Where gokrazy is the wrong choice

The failure mode is not a crash. It is discovering, three weeks in, that your workload needs something the system deliberately does not have. A Python script, a C library with a plugin directory, a shell script that runs at boot, a package installed from a repository: none of these have a place in a system whose stated design goal is to get rid of everything not strictly needed.

Debugging is the second constraint. Without a shell on the device, you are working through the supervision and status code paths in the system repository rather than logging in and poking around. The files status.go, statuslog.go and supervise.go exist for that reason, and the repository also carries httpsredirect.go and xsrf.go, which tells you the status surface is treated as a web-facing component with its own protections. If your team's operational reflex is to SSH in and inspect, this will feel like a wall until you build a different reflex.

The third case is a fleet with mixed requirements. gokrazy wants each device to be an appliance running Go programs. A device that also needs to act as a general-purpose host, run containers from arbitrary registries, or serve as a development box is not what this is for. The narrow supported platform list reinforces that boundary: Raspberry Pi 3, 4, 5, Zero 2 W, and x86_64 or ARM64 PCs. Older Pis and other ARM boards are not in the list.

How this differs from Buildroot and Yocto

The closest alternatives for building a small Linux image for a board are Buildroot and the Yocto Project. Both are general-purpose embedded Linux build systems. They give you a package and recipe framework, a configurable root filesystem, and the ability to include C programs, Python, BusyBox, systemd or whatever else you select. Their flexibility is the point, and it is also the maintenance surface.

gokrazy inverts that. Instead of a configurable root filesystem with a package selection step, you get a system whose contents are your Go programs plus the kernel and firmware pulled from the gokrazy repositories. There is no package selection because there is no package manager. The update mechanism lives in the running system (update.go) rather than in an external deployment tool.

The practical difference shows up in what you spend time on. With Buildroot or Yocto you spend it on configuration, recipe maintenance and rebuild times. With gokrazy you spend it on making sure your workload is expressible in Go and on understanding the supervision and update behaviour. If your application is already Go and already cross-compiles, gokrazy is a much shorter path. If your application is a mix of languages and system services, Buildroot or Yocto will accept it and gokrazy will not.

Maintenance, updates and what the licence covers

The last push to the repository was on 2026-09-16, and the repository is not archived. The go.mod declares Go 1.26, and several dependencies are pinned to pseudo-versions rather than tagged releases, including github.com/gokrazy/internal and github.com/anatol/vmtest. Pseudo-versions mean the dependency tracks a specific commit, so upgrading means deliberately moving that pin rather than accepting whatever the module proxy resolves.

Upgrade cost is concentrated in two places. First, the kernel and firmware repositories that the tools module pulls in: those move independently, and the README describes them as pre-built artifacts rather than something you build. Second, the Go toolchain itself, given the go directive in go.mod. The system repository's own dependency list is short and mostly low-level, which keeps the surface small, but it also means a change in golang.org/x/sys or vishvananda/netlink can reach into device and network behaviour.

The licence is BSD-3-Clause, which is permissive and generally compatible with shipping in a product. The repositories it pulls in for firmware, EEPROM and kernel artifacts may carry their own terms, and those are separate projects with separate LICENSE files. Check each one rather than assuming the top-level licence covers the assembled image. This is a description of what the repository states, not legal advice.

One thing to verify yourself: the README does not document a rollback procedure for a failed update. The presence of update.go and reboot.go tells you updates are handled in-system, but the recovery story is not in this README. Look for it on gokrazy.org before you deploy anything you cannot physically reach.

Editorial conclusion

Adopt gokrazy if you have one or more Go programs you already cross-compile and you want a device that boots straight into them without a distribution underneath: the repository layout, the supported platform list and the update code are all in place for that. Do not adopt it if you need a package manager, a shell on the device, or non-Go software installed at runtime; the project is built around removing exactly those things. Before committing, verify three specifics against the current docs at gokrazy.org: which of your target boards appears on the supported platforms page, how the tools module is meant to be obtained for your Go version, and what the update and rollback path looks like for your deployment.

Frequently asked questions

Official sources

1. gokrazy/gokrazy on GitHub
2. Issues
3. License: BSD-3-Clause
4. Project website
5. README