gonix

GoNIX - a UNIX-like Operating System with a mostly Go Userspace

gonix is a UNIX-like Operating System (based on the Linux Kernel) with a Userland mostly written in Go including Networking, Services, Device Management and an integrated SSH service.

Quick Start

Building GoNIX requires Docker (the build runs in an Alpine toolchain container). The ergonomic entrypoint is:

make image              # your machine's arch (arm64 on Apple Silicon, else amd64)
make image ARCH=amd64   # amd64: builds artefacts/boot.iso
make image ARCH=arm64   # arm64: builds artefacts-arm64/{boot.iso,Image,rootfs.gz}

Run it under QEMU:

./test.sh               # boot your machine's arch (SSH forwarded to :2222)
ARCH=amd64 ./test.sh    # boot the amd64 ISO
ARCH=arm64 ./test.sh    # boot arm64 (native under hvf on Apple Silicon)

Then SSH in with ssh -p 2222 root@localhost.

GoNIX authenticates SSH by public key only, and an image authorises no key of its own — so ./test.sh injects yours (~/.ssh/id_ed25519.pub, or whatever SSHKEY= names) at boot. On an image you did not boot yourself, authorise a key one of three ways:

The console is a separate matter: root has the password gonix there, which is only reachable from the VM's own screen or serial line, never over the network. Change it with passwd; add accounts with adduser and addgroup. What you add persists on an installed system alongside the image's own accounts (see Users and SSH access).

Supported Platforms

GoNIX targets virtual machines and cloud instances rather than bare-metal hardware: the kernel is built with just the device drivers needed by common hypervisors (with virtio as the preferred, fastest path) plus loadable modules disabled (everything is built in for the initramfs boot). Two architectures are supported:

amd64 (x86-64)

A BIOS-booted ISO that runs on essentially any x86-64 hypervisor or cloud instance. Device support:

• Network: virtio-net (preferred), and Intel e100 / e1000 / e1000e (the default emulated NIC on QEMU, VirtualBox and VMware).
• Storage: virtio-blk (preferred), SATA (AHCI) and IDE (PIIX) disks, and ATAPI CD-ROM (ISO9660) — so it boots from a CD/ISO and can use a virtio, SATA or IDE data disk.
• Console: VGA text console (tty0) and serial (ttyS0), so both graphical and headless/serial setups get kernel output and a login.
• Guest extras: KVM paravirt guest support and a hardware RTC.

An optional persistent root and the baseline firewall can be baked into the ISO at build time, e.g. make image PERSIST=/dev/vda FIREWALL=1. A persistent root makes the system an installed one, whose changes (installed packages included) survive reboots. Add SEAL=1 to seal it read-only instead, so only the allow-listed paths persist. See Configuration → Persistent root.

arm64 (aarch64)

Targets the QEMU virt board, booted directly via -kernel/-initrd (no BIOS/ISO). On an Apple Silicon host this runs natively under the hvf accelerator, so boots take seconds. Device support is deliberately minimal — virtio only:

• Network/Storage/Console: virtio-net, virtio-blk, virtio-console, virtio-rng, with the PL011 UART as the serial console.
• Platform: generic PCIe host bridge and GICv3 interrupt controller (the virt board); no SoC-vendor or physical-hardware drivers are included.

Enable the persistent root and/or firewall on the kernel cmdline with PERSIST=1 (which needs a root disk — make disks creates one) and/or FIREWALL=1:

PERSIST=1 FIREWALL=1 ARCH=arm64 ./test.sh

Services

Background services (the SSH server, DHCP client, web server, …) run under a supervisor in init and are managed at runtime with the sv command:

sv status            # list services and their state
sv restart sshd      # start / stop / restart a service

Services are defined by simple unit files in /etc/rc.d/. See docs/services.md for the sv commands and the unit format.

Packages

Software is managed with pkg, a CRUX-style package manager. Install binary packages (with automatic dependency resolution) from a repository, or build from source with a Pkgfile:

pkg update           # refresh the repository index
pkg install <name>   # install a package and its dependencies
pkg upgrade          # upgrade installed packages

See docs/packages.md for the full guide, including building packages and publishing a repository.

Configuration

System configuration lives in /etc/rc.conf (hostname, firewall), the kernel command line (persistence, firewall), and /etc/rc.local (boot script). See docs/configuration.md for the full guide, including networking, users/SSH, and what persists with a persistent root.

Library images

gonix packs a Go program into a bootable micro-VM with no userland: the GoNIX kernel, a slim init and your program, as a single hybrid ISO. Any program that builds with CGO_ENABLED=0 works unmodified.

go install git.mills.io/prologic/gonix/cmd/gonix@latest
cd ~/src/myserver
gonix pack .                  # writes myserver.iso, bootable on a cloud or a disk
gonix run -p 8080:8080 myserver.iso

See docs/library-images.md.

License

GoNix is licensed under the terms of the MIT License