---
title: gokrazy quickstart
aliases:
  - /quickstart.html
menu:
  main:
    title: "Quickstart"
    weight: 20
---

      <div class="row">
        <div class="col-lg-12">
	  <h1>Get a Raspberry Pi 3 or 4 (no others)</h1>
	  <p>
	  Currently, the Raspberry Pi 3 and Pi 4 are the <strong>only</strong>
	  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 <a href="https://www.reddit.com/r/golang/comments/5xgf8u/gokrazy_a_purego_userland_for_your_raspberry_pi_3/dei7b2m/">stapelberg’s
	  reddit comment about supported hardware</a>.
	  </p>

	  <h1>Install Go</h1>
	  <p>
	  If you don’t already have Go installed, install the latest <a href="https://golang.org/dl/">Go</a> version.
	  </p>

          <h1>Install the gokrazy packer</h1>
	  <p>
	    Create a directory for this gokrazy instance and initialize a Go module:
	  </p>
	  <pre>INSTANCE=gokrazy/hello
mkdir -p ~/${INSTANCE?}
cd ~/${INSTANCE?}
go mod init hello</pre>
	  <p>
	    Then, install the gokr-packer:
	  </p>
<pre>go get github.com/gokrazy/tools/cmd/gokr-packer@latest</pre>

          <h1>Overwrite an SD card with gokrazy</h1>
	  <p>
	  Plug an SD card into your card reader and locate its device node by checking <code>dmesg | tail</code>. In this example, we’ll assume the SD card is accessible as <code>/dev/sdb</code>.
	  </p>
	  <p>
	  To overwrite the entire SD card <code>/dev/sdb</code> with a gokrazy installation running a hello world program, use:
	  </p>
	  <pre>cd ~/gokrazy/hello
gokr-packer -overwrite=/dev/sdb github.com/gokrazy/hello github.com/gokrazy/serial-busybox</pre>
          <p>
	  The <code>gokr-packer</code> command above will result in log output like this:
	  </p>
          <pre>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:<i>&lt;automatically-generated-random-password&gt;</i>@gokrazy/

In addition, the following Linux consoles are set up:

	1. foreground Linux console on the serial port (115200n8, pin 6, 8, 10 for GND, TX, RX), accepting input
	2. secondary Linux framebuffer console on HDMI; shows Linux kernel message but no init system messages

Use -serial_console=disabled to make gokrazy not touch the serial port,
and instead make the framebuffer console on HDMI the foreground console</pre>
          <p>
	  After booting from this SD card, your Raspberry Pi 3 or 4 will:
	  <ul>
	  <li>obtain an IP address for hostname “gokrazy” via DHCP (IPv4) and SLAAC (IPv6)</li>
	  <li>synchronize the clock using NTP</li>
	  <li>expose a password-authenticated web interface on private IP addresses<br>
	  (the default password can be recovered from <code>~/.config/gokrazy/http-password.txt</code>)</li>
	  <li>supervise all installed programs (only the hello world program in this example)</li>
	  </ul>
	  The only way for you to interact with the device is via the
	  web interface (unless the installed programs provide other
	  ways). There will be no HDMI output, no serial console, etc.
	  </p>
	</div>
      </div>