Currently, the Raspberry Pi 4 B is the recommended platform for using gokrazy, but you can find other supported and upcoming platforms.
If you don’t already have Go installed, install the latest Go version.
Now that you have a working Go installation, install the
gok command line tool (CLI):
go install github.com/gokrazy/tools/cmd/[email protected]
watch -d1 ls -l '/dev/disk/by-id/*' and insert an SD card. Copy the
highlighted device name:
In this example, we’ll assume the SD card is accessible as
Create a directory for this gokrazy instance:
gok new # creates an instance named “hello” in --parent_dir default directory ~/gokrazy # alternatively, to use a different instance name: gok -i myname new
If you’re curious, you can run
gok edit to open the generated
To overwrite the entire SD card
/dev/sdx with a build of this
gokrazy installation, use:
gok overwrite --full /dev/sdx
The following packages are included in newly created instances by default:
The gokrazy packer builds each specified Go program
github.com/gokrazy/hello) in a separate build directory, each with its
go.mod file. See Working with Go modules for more
This is what the above
gok commands look like in action:
gokrazy gok ga84f00+ on GOARCH=amd64 GOOS=linux Build target: CGO_ENABLED=0 GOARCH=arm64 GOOS=linux Build timestamp: 2023-01-12T23:36:34+01:00 Loading system CA certificates from /etc/ssl/certs/ca-certificates.crt Building 4 Go packages: github.com/gokrazy/fbstatus github.com/gokrazy/hello github.com/gokrazy/serial-busybox github.com/gokrazy/breakglass will be started with command-line flags from /home/michael/gokrazy/hello/config.json last modified: 2023-01-12T23:36:23+01:00 (10s ago) [done] in 1.40s Including extra files for Go packages: github.com/gokrazy/breakglass will include extra files in the root file system from /home/michael/gokrazy/hello/breakglass.authorized_keys last modified: 2023-01-12T23:36:23+01:00 (12s ago) Including loadable kernel modules from: /home/michael/go/pkg/mod/github.com/gokrazy/[email protected]/lib/modules Feature summary: use GPT: true use PARTUUID: true use GPT PARTUUID: true 2023/01/12 23:36:36 partitioning /dev/disk/by-id/usb-TS-RDF5_SD_Transcend_000000000037-0:0 (GPT + Hybrid MBR) 2023/01/12 23:36:36 device holds 15931539456 bytes 2023/01/12 23:36:36 Re-reading partition table failed: permission denied. Remember to unplug and re-plug the SD card before creating a file system for persistent data, if desired. Creating boot file system [creating boot file system] Kernel directory: /home/michael/go/pkg/mod/github.com/gokrazy/[email protected] EEPROM update summary: pieeprom.upd (sig d1e44edf33) recovery.bin vl805.bin (sig 6246230ecd) [done] in 0.18s, 71 MiB MBR summary: LBAs: vmlinuz=51795 cmdline.txt=144875 PARTUUID: 4f9f2cab Creating root file system [done] in 0.33s If your applications need to store persistent data, unplug and re-plug the SD card, then create a file system using e.g.: mkfs.ext4 /dev/disk/by-partuuid/60c24cc1-f3f9-427a-8199-4f9f2cab0004 To boot gokrazy, plug the SD card into a supported device (see https://gokrazy.org/platforms/) Build complete! To interact with the device, gokrazy provides a web interface reachable at: http://gokrazy:<automatically-generated-random-password>@hello/ In addition, the following Linux consoles are set up: 1. foreground Linux framebuffer console on HDMI
It is safe to unplug your SD card once
After booting from this SD card, your device will:
HTTPPasswordkey of its
To interact with your device, you can:
gok newsets it up by default.
Congratulations! 🎉 You now have a working gokrazy installation!
Next, see the Configuration guide for details on how to use other programs.
If you prefer the serial console, you can optionally connect a serial adapter to
the Raspberry Pi and remove the
"SerialConsole": "disabled" line from your gokrazy
config.json to make the primary Linux console end up on the serial
Enter on the serial console, gokrazy will
interactively start either:
/tmp/serial-busybox/ash(provided by the serial-busybox package)
/perm/sh, if present (supplied by you, the user)