Installation

Installation

Status: alpha (0.2.x). Actively developed and daily-driven by the author, but early and fast-moving. Try it in a VM before you give it a disk.

---

Try it in QEMU first

git clone https://github.com/velle999/SYNAPSE.git && cd SYNAPSE
QEMU_RAM=8G ./archiso/build_scripts/qemu-test.sh   # auto-detects the newest ISO

Uses KVM when available, boots UEFI via OVMF (falling back to BIOS), and attaches a persistent 20 GB test disk. Give it 8 GB+ of RAM when the model is embedded — it's a 7B model, and it will thrash or OOM below that. Kernel and boot output are mirrored to the serial console: View → serial0 in the QEMU window.

---

Install to hardware

Grab the latest ISO from Releases and boot it.

Releases are split into .part* files because GitHub caps release assets at 2 GiB and the ISO is ~6.5 GB. Reassemble before writing:

cat SynapseOS-*.iso.part* > SynapseOS.iso
sha256sum -c SHA256SUMS          # if published alongside
sudo dd if=SynapseOS.iso of=/dev/sdX bs=4M status=progress oflag=sync

The default ISO embeds Mistral 7B Instruct (Q4_K_M, ~4.1 GB), so the AI is live on first boot with nothing to configure. Slim (--no-model) ISOs fetch the model on first boot via syn-firstboot — that one needs a network.

Then run the installer from the live session (syn-install).

Installing from a profile

Every question the installer asks can be answered ahead of time in a file, so an install is reproducible instead of re-typed:

syn-install --config profile.nix     # or a plain key=value file

Whatever the profile leaves out is still asked at the machine, so pinning just the disk layout and the package set is a perfectly good profile. The keys are semantic (filesystem = "btrfs", never a menu number), the destructive confirmations each need writing out, and a key that answers nothing is reported by name at the end rather than ignored.

Full key list and the Nix form: Nix → Install profiles. /usr/share/syn/nix/profile-example.nix documents every key on the machine.

---

Install modes

Everything below is in 0.2.5, the current release. On 0.2.4 and earlier the installer had ERASE and ALONGSIDE only, with an ext4 root and GRUB — no filesystem or bootloader choice, no snapshots, no ADVANCED mode, and no swap of any kind.

Mode	What it does
ERASE	Whole-disk install. Destructive.
ALONGSIDE	Non-destructive dual-boot — one ext4 root in the largest existing free region, reusing the machine's ESP. Offered on UEFI when the disk already holds an OS and has room
ADVANCED	You partition the disk yourself, then tell the installer which partitions to use

The ESP is mounted, never reformatted on the alongside path, because it carries the other OS's bootloader. So make free space first (shrink the Windows partition from Windows' own disk manager), then install.

Before anything is written, the installer prints the whole plan back — disk, mode, firmware, filesystem, bootloader, separate /boot, encryption, snapshots — and asks you to confirm it. Answering no restarts the questions; nothing has touched the disk at that point.

ADVANCED

For the layouts the automatic paths don't generate: a /home you want kept, an ESP the alongside conditions rejected, a partition left over from another distro.

It runs a partition editor on the target disk — cfdisk by default, or any of fdisk/parted/cgdisk/gdisk/gparted that the image actually has — re-reads the table when you exit, and then asks for:

• the root partition (required)
• the EFI System Partition (UEFI). An existing FAT one is kept by default; formatting it is a question, because on a dual-boot disk that is where the other OS's bootloader lives
• a separate /boot, when the filesystem + bootloader + encryption combination needs one
• a swap partition (optional — blank for none)

Only the partitions you name are formatted. Nothing else on the disk is touched, and it never writes a partition table of its own. Every answer is checked before it is used: a whole disk given where a partition was wanted, something already mounted, anything on the live USB, or a root too small are all refused with the reason, and it asks again rather than aborting the install.

Filesystem, bootloader and encryption are asked on this path exactly as on ERASE, and the same code formats the root — so LUKS and the btrfs subvolume layout are identical to an automatic install.

---

Filesystems

	Notes
ext4	The default. Boring in the way a root filesystem should be
btrfs	The only one with snapshots. Mounted with zstd:3 compression; lays out @, @home, @snapshots, @var_log, @pkg
xfs	Fast on large files. Cannot be shrunk
f2fs	Flash-oriented

Snapshots are a btrfs feature here — they are btrfs subvolume snapshots taken by snapper. ext4, xfs and f2fs have no equivalent (that would mean LVM thin snapshots, which this installer does not set up), and the installer says so rather than silently skipping the question.

Bootloaders

	Firmware	Can boot snapshots
GRUB	UEFI + BIOS	yes, via grub-btrfs
systemd-boot	UEFI only	no
limine	UEFI only	yes, via limine-snapper-sync

The ESP goes to /boot/efi under GRUB and is /boot under systemd-boot and limine, which read nothing but the ESP. That also sizes it: 512 MiB for GRUB, 1 GiB for systemd-boot, and 4 GiB for limine with snapshots on — that tool copies every retained snapshot's kernel and initramfs onto the ESP, roughly 150 MB each, and simply stops adding entries when the partition fills.

With encryption, systemd-boot or limine is the better choice: the kernel lives on the ESP and only the initramfs unlocks, so no separate unencrypted /boot partition is needed at all.

Snapshots

Offered when the root is btrfs and the bootloader can boot them. snapper takes a pre/post pair around every pacman transaction (snap-pac), and the boot menu grows entries for them. Timeline snapshots are off — hourly snapshots kept forever are how a btrfs system quietly fills its own disk — and the pacman ones are capped.

Swap

zram is set up on every install: compressed swap in RAM, sized min(RAM/2, 8 GiB) with zstd. It needs no partition, which is why it can apply to all three modes — ERASE and ALONGSIDE both give the root everything that is left.

A real swap partition is offered on the ADVANCED path only, for the two things zram cannot do: hibernate (the image has to survive power-off) and add capacity that is not itself RAM. Where both exist, zram takes priority and the disk partition is overflow. An existing swap is not re-made by default — mkswap changes its UUID, which is what another installed system's fstab and its hibernation resume= point at.

Full-disk encryption

The ERASE and ADVANCED paths offer LUKS2 on the root filesystem. It is deliberately not offered alongside an existing OS: encrypting into free space works in principle, but shipping an untested variant of the destructive path is worse than not offering it.

/boot is a separate plain partition, not inside the encrypted root. That is not an oversight:

• Putting /boot inside LUKS means GRUB must unlock it, and GRUB can only open LUKS2 volumes that use PBKDF2 — not the argon2id that cryptsetup defaults to and that makes LUKS2 worth using.
• The alternatives are weakening the KDF or fighting GRUB's cryptodisk support, and GRUB is already the most fragile part of this distro's boot path.
• A separate /boot costs one partition and leaves the initramfs as the only thing that unlocks anything.

The ESP itself can never be encrypted — firmware has to read it.

Manage it afterwards with syn-crypt:

syn-crypt status                       # is root actually encrypted?
syn-crypt add-key                      # a second passphrase
syn-crypt change-key
syn-crypt backup-header /run/media/…/luks-header.img

Back the header up. A corrupted LUKS header means the data is gone even with the right passphrase. syn-crypt refuses to guess a device — it either takes one explicitly or resolves it from the actually-mounted root, because a LUKS operation on the wrong device destroys a disk.

---

Requirements

Arch	x86-64
RAM	8 GB minimum with the embedded model (it's a 7B)
Disk	~20 GB
GPU	Optional. The ISO ships a CPU llama build so it starts anywhere.

On GPU: the shipped ISO runs synapd on the CPU by design — a CUDA-linked build needs libcuda.so.1 and would fail to start on any machine without an NVIDIA driver. After installing, switch to the CUDA package (synapse-llama-cuda) to get GPU offload. Then verify it, because this specific thing lied to us for months:

grep -c nvidia /proc/$(pidof synapd)/maps   # 0 means you are still on the CPU

See synapd.

---

After installing

Everything starts on boot:

systemctl status synapd      # AI inference daemon
systemctl status synguard    # security monitor
systemctl status synnet      # network policy
lsmod | grep synapse_kmod    # kernel module
cat /sys/kernel/synapse/status

Open a shell and you should see ⚡ AI online. Press Super+C for the control panel, which lists every keyboard shortcut — see Keybindings.

Wi-Fi: Super+I, or the bar's network module. Installing over Wi-Fi is supported.

Make it yours: Super+T themes, Super+W wallpaper, Super+Shift+P cursors, Super+S sounds (silent until you turn them on), Super+Shift+A desktop widgets, Super+E window effects (off by default on a fresh install).

---

Secure Boot

Not enabled by default, and enabling it is a deliberate exercise — see Secure Boot. The one-line version: sbctl cannot enroll keys until the firmware is in Setup Mode, and rebooting will never put it there no matter what sbctl's error message implies. You must clear the Platform Key from the BIOS menu. Run syn-secureboot enroll, which checks this for you.