Quickstart

Prep: pick a supported device

Currently, the Raspberry Pi 4 B is the recommended platform for using gokrazy, but you can find other supported and upcoming platforms.

Prep: Install Go

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

Prep: Install the gok CLI

Now that you have a working Go installation, install the gok command line tool (CLI):

go install github.com/gokrazy/tools/cmd/gok@main

Step 1: Insert an SD card

Run watch -d1 ls -l '/dev/disk/by-id/*' (see the permanent data section for macOS instructions) and insert an SD card. Copy the highlighted device name:

In this example, we’ll assume the SD card is accessible as /dev/sdx.

Step 2: Create a gokrazy instance and overwrite an SD card with gokrazy

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

The --parent_dir can also be changed permanently by setting the GOKRAZY_PARENT_DIR environment variable.

If you’re curious, you can run gok edit to open the generated config.json in your editor.

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:

  • github.com/gokrazy/fbstatus
  • github.com/gokrazy/hello
  • github.com/gokrazy/serial-busybox

The gokrazy packer builds each specified Go program (e.g. github.com/gokrazy/hello) in a separate build directory, each with its own go.mod file. See Working with Go modules for more details.

This is what the above gok commands look like in action:

Click here to show the gok log output 
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/kernel@v0.0.0-20230111172439-0cd82b0bec82/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/kernel@v0.0.0-20230111172439-0cd82b0bec82
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 gok returns.

Step 3: Boot gokrazy

After booting from this SD card, your device will:

  • display system status on the monitor connected via HDMI, if any
  • 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
    (each instance gets its own password in the Update → HTTPPassword key of its config.json, see gok edit)
  • supervise all installed programs (only the hello world program in this example)

To interact with your device, you can:

  1. Open the gokrazy web interface in your browser (easiest option)
  2. Attach a serial console (see below)
  3. Use the breakglass package to start an interactive SSH session. gok new sets 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.

Optional: Using the serial console

See also: Configuration → Instance Config Reference → SerialConsole

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 instance’s config.json to make the primary Linux console end up on the serial console.

When pressing Enter on the serial console, gokrazy will interactively start either:

  1. /tmp/serial-busybox/ash (provided by the serial-busybox package)
  2. /perm/sh, if present (supplied by you, the user)