Installing on Bare Metal¶

This guide covers installing tuinix on a real physical machine.

Supported Architectures¶

Architecture	ISO	Target Devices
x86_64	`tuinix.VERSION.x86_64.iso`	Standard PCs, laptops, servers
aarch64	`tuinix.VERSION.aarch64.iso`	ARM64 devices with UEFI boot

Hardware Requirements¶

Resource	Minimum	Recommended
CPU	x86_64 or aarch64	Modern multi-core (AMD Ryzen / Intel Core / ARM64)
RAM	4 GB	8 GB+
Storage	20 GB	50 GB+ (SSD strongly recommended)
Boot mode	UEFI	UEFI

UEFI and Secure Boot

tuinix requires UEFI boot. Legacy BIOS is not supported. Secure Boot must be disabled when using ZFS because ZFS kernel modules are unsigned.

Step 1: Get the ISO¶

Download the latest ISO from the releases page, or build it yourself:

git clone https://github.com/timlinux/tuinix.git
cd tuinix

# Build for x86_64 (default)
./scripts/build-iso.sh

# Build for aarch64 (ARM64)
./scripts/build-iso.sh aarch64

# Build both architectures
./scripts/build-iso.sh both

Internet required

An internet connection is needed during installation to download packages from the NixOS binary cache.

Step 2: Flash the ISO to a USB drive¶

Every ISO ships with a matching checksum file (tuinix-<arch>-<version>.md5). Verify your download first:

md5sum -c tuinix-x86_64-*.md5

You need a USB drive of at least 4 GB. All data on the drive will be destroyed.

LinuxmacOSWindows

# Identify your USB device (check with lsblk first!)
sudo dd if=tuinix-*.iso of=/dev/sdX bs=4M status=progress oflag=sync

Replace /dev/sdX with your actual USB device (e.g. /dev/sdb). Triple-check you have the right device -- dd will happily overwrite your main disk.

# Find the disk number with diskutil list
diskutil unmountDisk /dev/diskX
sudo dd if=tuinix-*.iso of=/dev/rdiskX bs=4m
diskutil eject /dev/diskX

Use one of these tools:

Rufus -- select "DD Image" mode
balenaEtcher -- works out of the box

Step 3: Configure BIOS/UEFI¶

Before booting from USB, enter your BIOS/UEFI settings (typically by pressing F2, F12, DEL, or ESC during POST):

Boot mode: Set to UEFI (disable CSM/Legacy if present)
Secure Boot: Disable it
Boot order: Set USB as first boot device, or use the one-time boot menu

Tip

Many machines have a one-time boot menu (often F12) that lets you select the USB without changing permanent settings.

Network connectivity (optional)¶

Since the tuinix ISO includes all packages for offline installation, network connectivity is optional for standard configurations. However, if your configuration adds packages beyond the standard set, or you want to pull the latest updates, an internet connection may be useful.

Here are several options for getting online from the live environment:

Ethernet (automatic)¶

If you have a wired Ethernet connection, DHCP runs automatically and you should be online immediately.

iPhone USB tethering¶

The live ISO includes iPhone USB tethering support out of the box:

Connect your iPhone via USB cable
On your iPhone, enable Settings → Personal Hotspot
When prompted, choose Trust this computer
The iPhone should appear as a network interface (check with ip link)
Run sudo dhcpcd eth1 (or whichever interface name your iPhone appears as)

Finding the iPhone interface

Run ip link to see all interfaces. The iPhone typically appears as eth1 or similar after connection.

WiFi¶

The live environment ships impala, a friendly TUI for WiFi management (backed by iwd). Just run:

impala

Select your network, enter the passphrase, and you are connected — DHCP is handled automatically. If you prefer the command line, iwctl is also available:

iwctl station wlan0 connect "SSID"

Rescue SSH access¶

The SSH server is installed on the live ISO but not started — the live root password is well known, so exposing sshd unsolicited would be unsafe. If you need remote access for a rescue session:

passwd                  # set a strong root password first!
systemctl start sshd
ip addr                 # find your IP, then ssh root@<ip> from elsewhere

Step 4: Run the installer¶

Once the USB boots, you'll land in /home/tuinix with a welcome message showing the mascot and install instructions. Run:

sudo installer

The interactive TUI installer will guide you through:

Network check -- the installer checks internet connectivity. This can be skipped for offline installations since all packages are pre-cached on the ISO.
Username -- enter your login username
Full name -- your display name (used in git config)
Email -- your email address (used in git config)
Password -- set your login password (entered twice to confirm)
Hostname -- name your machine
Storage mode -- choose your disk layout strategy (see Storage Modes below)
Disk selection -- choose the target disk(s)
ZFS encryption passphrase -- set a passphrase for full-disk encryption (skipped for XFS mode)
Locale and keyboard -- select your region and layout
SSH server -- choose whether to enable the OpenSSH server on the installed system (see SSH Server below)
Confirmation -- review the summary, type DESTROY to confirm
Installation -- partitioning, formatting, and NixOS install run automatically. A live log tail is displayed so you can monitor progress.

Storage Modes¶

The installer supports six storage modes:

Encrypted ZFS (single disk) -- recommended¶

The default and most common option. A single disk is partitioned with an EFI boot partition and an encrypted ZFS pool. All data is protected with AES-256-GCM encryption and you get ZFS features like compression (zstd), snapshots, and data integrity checking.

XFS unencrypted (single disk) -- maximum performance¶

A single disk with an EFI boot partition and an XFS root partition. No encryption, no ZFS overhead. This gives maximum raw I/O performance and uses the latest available kernel (not constrained by ZFS compatibility). Choose this when performance matters more than encryption or ZFS features.

XFS unencrypted (existing partition) -- dual-boot¶

Install tuinix on pre-existing partitions without erasing the entire disk. This is ideal for dual-boot setups or machines with a pre-partitioned disk layout. You select an existing boot/ESP partition and an existing root partition:

The boot/ESP partition is used as-is (not reformatted) -- it must already contain a valid FAT32 filesystem
The root partition is formatted with XFS -- all existing data on this partition will be destroyed
Other partitions on the disk are left untouched
GRUB is installed to its own EFI directory (/boot/EFI/NixOS/) so it does not conflict with existing bootloaders
GRUB os-prober auto-detects other operating systems on the machine

Preparing partitions

Before running the installer, use a partitioning tool (e.g. fdisk, gdisk, or parted) to create the partitions you need. You need at least:

An EFI System Partition (ESP) of at least 100 MB, formatted as FAT32
A root partition of at least 20 GB for the operating system

Encrypted ZFS stripe (multi-disk) -- combined space¶

Two or more disks are combined into a single encrypted ZFS pool with no redundancy (like RAID0). You get the sum of all disk capacities. If any disk fails, all data is lost. Use this when you need maximum space from multiple disks and have a backup strategy.

Encrypted ZFS raidz (multi-disk) -- 1-disk fault tolerance¶

Three or more disks in a raidz configuration (like RAID5). One disk's worth of space is used for parity, the rest is usable. Any single disk can fail and be replaced without data loss. This is a good balance of space efficiency and safety.

Encrypted ZFS raidz2 (multi-disk) -- 2-disk fault tolerance¶

Four or more disks in a raidz2 configuration (like RAID6). Two disks' worth of space is used for parity. Any two disks can fail simultaneously without data loss. Use this for critical data that needs maximum redundancy.

Multi-disk selection

For multi-disk modes, use Space to toggle each disk on/off and Enter to confirm your selection. The first selected disk will host the EFI boot partition.

SSH Server¶

The installer optionally configures SSH access on the installed system. When enabled:

The OpenSSH server listens on port 22
The firewall is enabled with port 22 open
Password authentication is disabled for security
Root login via password is prohibited (key-based only)
You will be prompted for a GitHub username so the installer can fetch your public SSH keys and add them to your authorized keys

This is recommended for servers and headless machines. If you skip SSH during installation, you can enable it later by adding the following to your host configuration:

tuinix.security.ssh.enable = true;
tuinix.security.firewall.enable = true;

Then rebuild with sudo nixos-rebuild switch --flake .#<hostname>.

Step 5: First boot¶

Remove the USB drive
Reboot
At the GRUB menu, select tuinix
If using an encrypted ZFS mode, enter your encryption passphrase when prompted
Log in with the username and password you set during installation

Disk layout¶

The installer creates one of these layouts depending on the chosen storage mode:

Encrypted ZFS (single disk)¶

Partition	Size	Filesystem	Purpose
ESP	5 GB	FAT32	EFI System Partition (`/boot`)
ZFS	Remainder	ZFS (encrypted)	Root pool `NIXROOT`

ZFS datasets created:

Dataset	Mountpoint	Notes
`NIXROOT/root`	`/`	Root filesystem (blank snapshot taken)
`NIXROOT/nix`	`/nix`	Nix store (5% of disk, min 20 GB)
`NIXROOT/home`	`/home`	User data (snapshots enabled)
`NIXROOT/overflow`	`/overflow`	Extra storage (snapshots enabled)
`NIXROOT/atuin`	`/var/atuin`	Shell history (XFS zvol)

XFS unencrypted (single disk)¶

Partition	Size	Filesystem	Purpose
ESP	5 GB	FAT32	EFI System Partition (`/boot`)
Root	Remainder	XFS	Root filesystem (`/`)

XFS unencrypted (existing partition)¶

Uses pre-existing partitions selected by the user. Only the root partition is formatted.

Partition	Action	Filesystem	Purpose
Boot/ESP (user-selected)	Mounted (not reformatted)	FAT32	EFI System Partition (`/boot`)
Root (user-selected)	Formatted with XFS	XFS	Root filesystem (`/`)

All other partitions on the disk remain untouched.

Multi-disk ZFS (stripe, raidz, raidz2)¶

The first disk gets an EFI boot partition; all disks contribute a ZFS partition to the pool.

Component	Description
ESP (disk 0 only)	5 GB FAT32 EFI boot partition
ZFS partitions	One per disk, combined into a single encrypted pool

The pool mode determines redundancy:

Mode	Usable space (N disks)	Fault tolerance
Stripe	N disks	None
Raidz	N-1 disks	1 disk failure
Raidz2	N-2 disks	2 disk failures

ZFS datasets are the same as the single-disk encrypted ZFS layout.

Default Packages¶

Every tuinix installation includes these packages out of the box:

Networking:

NetworkManager with nmtui for easy WiFi/network configuration
iPhone USB tethering support (libimobiledevice, usbmuxd, ifuse)

Core Tools:

vim, git, curl, wget, htop, tree

ZFS Features (x86_64 only):

Full ZFS support with encryption, compression, and snapshots
Native ZFS kernel modules

Architecture Differences

ZFS is only available on x86_64 installations. On aarch64, the XFS storage mode is used instead for maximum compatibility.

Post-installation¶

After installation, the flake is copied to two locations:

/etc/tuinix -- system reference copy
/home/<username>/tuinix -- your working copy (a git repo tracking upstream)

Your user configuration is at users/<username>.nix and includes:

User account settings
Home-manager git configuration with your name and email
Default groups (wheel, networkmanager, audio, video, docker)

To make changes to your system configuration:

cd ~/tuinix
# Edit configuration files
sudo nixos-rebuild switch --flake .#<hostname>

To pull upstream changes:

cd ~/tuinix
git pull
sudo nixos-rebuild switch --flake .#<hostname>

See the Post-Install Guide for more about your new environment.

Install log¶

The installer writes a detailed log to /tmp/tuinix-install.log during installation. This log is automatically copied to your home directory (/home/<username>/tuinix-install.log) so it persists after the first reboot. Check this log if you encounter any issues.

Recovery¶

If your system won't boot:

ZFS installsXFS installs

Boot from the installation USB again

Import and unlock your ZFS pool:

sudo zpool import -f NIXROOT
sudo zfs load-key -a
sudo zfs mount -a

Chroot in:
```
sudo nixos-enter --root /mnt
```

Fix and rebuild:

nixos-rebuild boot --flake /etc/tuinix#<hostname>

Boot from the installation USB again

Mount your root partition:

sudo mount /dev/sdX2 /mnt
sudo mount /dev/sdX1 /mnt/boot

Chroot in:
```
sudo nixos-enter --root /mnt
```

Fix and rebuild:

nixos-rebuild boot --flake /etc/tuinix#<hostname>

Troubleshooting¶

Symptom	Cause	Fix
USB doesn't boot	BIOS in Legacy mode	Switch to UEFI, disable CSM
Black screen after GRUB	Secure Boot enabled	Disable Secure Boot in BIOS
"no such pool available"	Disk has no `/dev/disk/by-id/` entry	Rare on real hardware; check disk WWN with `ls -la /dev/disk/by-id/`
Installation fails	Not enough disk space	Need at least 20 GB free
Can't type passphrase	Wrong keyboard layout in initrd	Reinstall with correct keyboard layout
"path not found" during install	Package not available in cache	Check internet connection and retry
`grub_is_shim_lock_enabled` error	GRUB module version conflict on shared ESP	Boot from USB, chroot in, run `rm -rf /boot/grub && nixos-rebuild boot --flake /etc/tuinix#<hostname>`