gokrazy

Get a Raspberry Pi 3 or 4 (no others)

Currently, the Raspberry Pi 3 and Pi 4 are the only supported models. Many people assume the Raspberry Pi Zero W could be used as well. Unfortunately, it uses the older BCM2835 SoC, which is not arm64, so gokrazy won’t run on it. See also stapelberg’s reddit comment about supported hardware.

Install Go

If you don’t already have Go installed, install the latest Go version.

Install the gokrazy packer

Create a directory for this gokrazy instance and initialize a Go module: 

INSTANCE=gokrazy/hello
mkdir -p ~/${INSTANCE?}
cd ~/${INSTANCE?}
go mod init hello

Then, install the gokr-packer: 

go install github.com/gokrazy/tools/cmd/[email protected]

Overwrite an SD card with gokrazy

Plug an SD card into your card reader and locate its device node by checking dmesg | tail. In this example, we’ll assume the SD card is accessible as /dev/sdb.

To overwrite the entire SD card /dev/sdb with a gokrazy installation running a hello world program, use: 

cd ~/gokrazy/hello
gokr-packer \
  -overwrite=/dev/sdb \
  -serial_console=disabled \
  github.com/gokrazy/fbstatus \
  github.com/gokrazy/hello \
  github.com/gokrazy/serial-busybox

The gokr-packer command above will result in log output like this: 

2017/03/01 20:59:55 packer.go:85: installing [github.com/gokrazy/hello]
2017/03/01 20:59:56 packer.go:131: partitioning /dev/sdb
2017/03/01 20:59:56 parttable.go:40: device holds 15931539456 bytes
2017/03/01 20:59:56 packer.go:139: waiting for /dev/sdb1 to appear
If your applications need to store persistent data, create a file system using e.g.:

	mkfs.ext4 /dev/sdb4

To boot gokrazy, plug the SD card into a Raspberry Pi 3 or 4 (no other models supported)

To interact with the device, gokrazy provides a web interface reachable at:

	http://gokrazy:<automatically-generated-random-password>@gokrazy/

In addition, the following Linux consoles are set up:

	1. foreground Linux framebuffer console on HDMI

After booting from this SD card, your Raspberry Pi 3 or 4 will:

  • display system status on the HDMI output
  • obtain an IP address for hostname “gokrazy” via DHCP (IPv4) and SLAAC (IPv6)
  • synchronize the clock using NTP
  • expose a password-authenticated web interface on private IP addresses
    (the default password can be recovered from ~/.config/gokrazy/http-password.txt)
  • supervise all installed programs (only the hello world program in this example)

The only way for you to interact with the device is via the web interface (unless the installed programs provide other ways).

A good next program to try is breakglass, which allows you to run an interactive SSH session to explore the system.

Serial console

If you prefer the serial console, you can optionally connect a serial adapter to the Raspberry Pi and remove the -serial_console=disabled flag to make the primary Linux console end up on the serial console.

When pressing Enter on the serial console, gokrazy will start the program /perm/sh if present. You can for example rename a statically linked busybox arm64 binary to sh, store it in the SD card’s persistent data partition, and use it as an interactive shell.