Quickstart :: gokrazy

Edit this page

# 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

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)