Quick start

QEMU on x86-64

The ISO boots a fixed kernel command line, so your key goes in through a cloud-init seed — a tiny second CD-ROM. tools/mkseed.sh in the repo builds one, or roll it by hand (a volume labelled cidata holding meta-data and user-data).

$ curl -LO https://pkgs.ulinux.org/images/gonix-amd64.iso
$ tools/mkseed.sh ~/.ssh/id_ed25519.pub seed.iso
$ qemu-system-x86_64 -m 1G -cdrom gonix-amd64.iso \
    -drive file=seed.iso,index=1,media=cdrom \
    -device virtio-rng-pci \
    -nic user,hostfwd=tcp::2222-:22
$ ssh -p 2222 root@localhost

The Go userspace is at a login prompt in ~20 ms — faster than you can blink.

Without the seed the VM still boots fine; you just log in at the console (root / gonix) rather than over SSH.

Rolling the seed by hand, if you’d rather not fetch the repo:

$ mkdir -p seed && cd seed
$ printf 'instance-id: gonix\nlocal-hostname: gonix\n' > meta-data
$ printf '#!/bin/sh\nmkdir -p /root/.ssh\ncat > /root/.ssh/authorized_keys << EOF\n%s\nEOF\n' \
    "$(cat ~/.ssh/id_ed25519.pub)" > user-data
$ cd .. && xorrisofs -J -r -V cidata -o seed.iso seed/

The volume label must be cidata — that is what cloud-init looks for. On macOS without xorrisofs, use hdiutil makehybrid -iso -joliet -default-volume-name cidata -o seed.iso seed/.

QEMU on arm64 (Apple Silicon)

The fastest arm64 path is the bare kernel + initramfs, booted natively under HVF:

$ curl -LO https://pkgs.ulinux.org/images/gonix-arm64-Image
$ curl -LO https://pkgs.ulinux.org/images/gonix-arm64-rootfs.gz
$ qemu-system-aarch64 -machine virt,accel=hvf -cpu host -m 1G \
    -kernel gonix-arm64-Image -initrd gonix-arm64-rootfs.gz \
    -append "console=ttyAMA0 gonix.sshkey=$(base64 < ~/.ssh/id_ed25519.pub | tr -d '\n')" \
    -device virtio-rng-pci \
    -nic user,hostfwd=tcp::2222-:22 -nographic
$ ssh -p 2222 root@localhost

Two things that line is doing:

• gonix.sshkey= authorises your public key at boot. It takes base64 because the kernel splits its command line on spaces and a key has spaces in it. Give the option more than once to authorise more than one key.
• console=ttyAMA0 puts the kernel log and a login on the serial line, which is where -nographic leaves you.

The virtio-rng device seeds the kernel CRNG so the SSH host key can be generated at boot — see the VirtualBox tab for what happens without one.

VirtualBox on Apple Silicon

GoNIX also ships a UEFI-bootable arm64 ISO. In VirtualBox 7.1+ create an ARM 64-bit VM, attach the ISO, and boot — you log in at the VM console window.

https://pkgs.ulinux.org/images/gonix-arm64.iso

A few VirtualBox-on-ARM specifics:

• Give the VM a USB keyboard and USB mouse with a USB controller enabled — the ARM platform has no PS/2 controller, so VirtualBox’s default PS/2 input never reaches the guest and the console won’t accept keystrokes. Enable a USB controller (xHCI) under the VM’s USB settings, then: VBoxManage modifyvm <vm> --keyboard usb --mouse usb --usbxhci on. Use a relative USB mouse (--mouse usb), not the absolute USB tablet: VirtualBox’s ARM target doesn’t deliver the tablet’s absolute coordinates, so “Mouse Integration” stays greyed out and the desktop (startgui) cursor won’t move. With a relative mouse the cursor is captured into the window instead — release it with the Host key.
• Set the network adapter to Intel PRO/1000 (e1000) — VirtualBox’s ARM virtio-net is unreliable; GoNIX’s kernel drives e1000.
• If a reboot shows “No bootable option or device was found”, reset the VM’s UEFI variable store (VBoxManage modifynvram <vm> inituefivarstore) — a quirk of VirtualBox’s preview ARM firmware, not the ISO.
• Log in at the console window. SSH-over-NAT does not work yet: VirtualBox’s ARM preview exposes no random-number source, so the kernel can’t seed enough entropy to generate an SSH host key (see the note below). The console is fully functional.

For a full SSH-reachable arm64 box, use QEMU + UEFI firmware (edk2/AAVMF), which provides a virtio-rng device:

$ curl -LO https://pkgs.ulinux.org/images/gonix-arm64.iso
$ tools/mkseed.sh ~/.ssh/id_ed25519.pub seed.iso
$ qemu-system-aarch64 -machine virt,accel=hvf -cpu host -m 1G \
    -drive if=pflash,format=raw,readonly=on,file=edk2-aarch64-code.fd \
    -cdrom gonix-arm64.iso -device virtio-gpu-pci -device virtio-rng-pci \
    -drive file=seed.iso,if=none,id=cidata,format=raw,readonly=on \
    -device virtio-blk-pci,drive=cidata \
    -nic user,hostfwd=tcp::2222-:22
$ ssh -p 2222 root@localhost

The seed is attached as a virtio disk rather than a second CD-ROM because the arm64 virt machine has no IDE/SATA bus for one.

Note — environments without a hardware RNG. GoNIX relies on the kernel CRNG being seeded at boot, which on a VM means the hypervisor exposing an entropy source (a virtio-rng device, an EFI RNG, or a CPU RNG instruction). QEMU/KVM and cloud providers all do; VirtualBox’s experimental ARM target does not. Without one, the CRNG never initialises, so anything needing secure randomness (the SSH host key, TLS) blocks — the console still works. Always give arm64 VMs a virtio-rng device where you can.

Any cloud with custom-ISO boot

GoNIX boots the live ISO directly — no install-to-disk — so the instance’s disk is free for your data. Point your provider at the public ISO URL:

https://pkgs.ulinux.org/images/gonix-amd64.iso

On first boot, GoNIX’s cloud-init pulls your SSH key and hostname from the provider’s metadata service (NoCloud and Vultr are supported today), so you land on a configured server with nothing baked in — this is the one case where you need do nothing at all about keys.

Vultr, declaratively

resource "vultr_iso_private" "gonix" {
  url = "https://pkgs.ulinux.org/images/gonix-amd64.iso"
}

resource "vultr_instance" "gonix" {
  region   = "sgp"
  plan     = "vc2-1c-1gb"
  hostname = "gonix"
  iso_id   = vultr_iso_private.gonix.id
}

terraform apply, and Vultr fetches the ISO and boots it. This very site runs exactly this way — the GoNIX repo has the full cloud-init-driven deploy (site + Let’s Encrypt TLS, reproducible from terraform apply alone).