Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting started

Early / preview. A first bootable solnix image now exists — an unstable-edition x86_64 ISO + raw disk image (v2026.08.07), preview-grade: see Download. Also live: the binary cache (cache.solnix.io) and package search (search.solnix.io). Treat the image as a preview for testing in a VM, not a daily driver. The install steps below will firm up as the images stabilize.

New here entirely? Start with the introduction for what solnix is and how it is put together, then come back.

Try it in your browser (no install)

The fastest look at solnix needs nothing installed: https://solnix.io/tryit boots a real solnix riscv64 kernel in a WebAssembly RISC-V emulator — OpenSBI → kernel → init → a live $ shell running the actual coreutils. Try ls, cat /etc/release, echo hi.

Two things to expect. It runs the kernel’s full self-test log before the prompt (fork/exec, copy-on-write faults, SMP + IPI wakeup, timer preemption, FP context switching), so the $ takes a minute or two to appear — that scrolling log is the boot, not a hang. And it is a demonstration image: its runtime linker prints a few [ld.so.1] proof lines before every command, and the minimal /bin/sh has no pipes or > redirection.

This is also the honest state of the RISC-V port: the kernel boots to a shell, but there is no riscv64 builder or binary cache yet (see CPU support).

Try the preview image

The first bootable image (v2026.08.07, unstable/preview — for a VM, not a daily driver) is on the download page. Quickest way to see it boot, in a VM:

# fetch + verify the ISO (checksum is on the download page / release manifest)
curl -LO https://cache.solnix.io/images/release-224-v2/solnix-x86_64-minimal.iso
sha256sum solnix-x86_64-minimal.iso        # compare to the published sum

# boot it in QEMU (BIOS or UEFI; the ISO is hybrid-bootable)
qemu-system-x86_64 -m 4096 -smp 2 -cdrom solnix-x86_64-minimal.iso

There is also a raw disk image (solnix-raw.img.gz) for writing to a disk or attaching directly. Expect rough edges — this is an early preview to kick the tires, report what breaks, and help the arches along, not a supported install.

Use the binary cache

If you build software that solnix has already built, point nix at the cache and skip the recompilation:

# /etc/nix/nix.conf
substituters       = https://cache.solnix.io https://cache.nixos.org
trusted-public-keys = cache.solnix.io-1:8UNrVAOSOrI9PGHc8/pD2Yqp265ZeYb3OId+gv4+wm8= cache.nixos.org-1:6NCHdD59EeA7KA8wG4nSXk...

Prove the cache is real before you commit any config to it — ask it directly, no setup required:

$ nix store info --store https://cache.solnix.io
Store URL: https://cache.solnix.io
Public key: cache.solnix.io-1:8UNrVAOSOrI9PGHc8/pD2Yqp265ZeYb3OId+gv4+wm8=

Every store path is signed with the cache.solnix.io-1 key and Nix verifies the signature before use, so it does not matter where the bytes came from. See The binary cache for the full story, including the planned BitTorrent distribution and how seeding works.

Search for packages

Browse the package registry at search.solnix.io — BM25-ranked full-text search across the solnix package set. It answers the question you actually have: is X packaged, and for which arch? See Package search.

Read the man pages

The man pages that ship with cached packages are browsable at solnix.io/docs — A–Z by package and section. Coverage is early (it grows as packages land), and every package in search links straight to its own man pages; for anything not yet indexed, the upstream illumos man pages are the reference.

Cross-compile from Linux

You do not need an illumos box to build for solnix. From a Linux machine with Nix, add the cache above and build against the x86_64-solaris / aarch64-solaris platforms — prebuilt store paths come straight from the cache instead of being recompiled locally. This is how the non-primary architectures are populated today (see the news on cross-build artifacts). What does not cross-build from Linux is illumos-gate itself; see How solnix is built for why, and CPU architecture support for per-arch status.

Contribute

The project lives at:

  • Infra + services: codeberg.org/gregburd/solnix-infra
  • Site + handbook: codeberg.org/gregburd/solnix-site
  • The distribution itself: the solnix repo (illumos + Nix work)

Ports, packaging, and docs are all open. See Contributing.