Installation

Status: 1.0. Actively developed and daily-driven by the author, and ready for you to do the same. QEMU below is the quickest way to look around before you commit 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 if you install the 7B model — it will thrash or OOM below that. The ISO itself no longer carries one, which is part of why it boots in QEMU as comfortably as it does. Kernel and boot output are mirrored to the serial console: View → serial0 in the QEMU window.

Install to hardware

Download the ISO from soslinux.org — one file, about 4.6 GB, and resumable if your connection drops. The same image is mirrored on the Internet Archive, which also carries a torrent for it.

Check it before you write it. A download that stopped early still looks like an ISO, still writes to a stick, and fails later in ways that look like bad hardware.

Checking and writing: Linux / macOS

sha256sum -c SynapseOS-<ver>-x86_64.iso.sha256    # shasum -a 256 -c on macOS
sudo dd if=SynapseOS-<ver>-x86_64.iso of=/dev/sdX bs=4M status=progress oflag=sync

Find /dev/sdX with lsblk first, and write to the disk (/dev/sdb), not a partition on it (/dev/sdb1).

Checking and writing: Windows

In PowerShell, in the folder you downloaded to. It prints True when the download is intact:

(Get-FileHash -Algorithm SHA256 .\SynapseOS-<ver>-x86_64.iso).Hash -eq (((Get-Content .\SynapseOS-<ver>-x86_64.iso.sha256) -split '\s+')[0]).ToUpper()

(Get-FileHash prints uppercase hex where sha256sum writes lowercase — same bytes, which is what the .ToUpper() is for.) In Command Prompt instead, certutil -hashfile SynapseOS-<ver>-x86_64.iso SHA256, and compare it against the contents of the .sha256 file yourself.

Then write it with Rufus in DD Image mode, balenaEtcher, or by copying the .iso onto a Ventoy stick.

Or download it in parts, from GitHub

The release page carries the same image split into .part* files, because GitHub caps a release asset at 2 GiB and the ISO is larger than that — three parts, as of 1.0.0, and the count grows with the image, so count the assets on the release page rather than trusting this sentence.

The single-file download above is the easier road. This one exists for anyone who would rather take the image from GitHub, and for when a mirror is unreachable. Download every .part* file plus SynapseOS-<ver>-x86_64.iso.sha256 into one folder, then join them. The join is a plain byte-for-byte concatenation; the checksum is what tells you it worked.

On Linux or macOS:

cat SynapseOS-<ver>-x86_64.iso.part* > SynapseOS-<ver>-x86_64.iso
sha256sum -c SynapseOS-<ver>-x86_64.iso.sha256

To check the parts before joining rather than the ISO after: sha256sum -c SynapseOS-<ver>-x86_64.iso.parts.sha256.

On Windows, in Command Prompt, in the folder you downloaded to (Shift+right-click the folder ▸ Open in Terminal, or cd to it):

copy /b SynapseOS-<ver>-x86_64.iso.part00 + SynapseOS-<ver>-x86_64.iso.part01 + SynapseOS-<ver>-x86_64.iso.part02 SynapseOS-<ver>-x86_64.iso

Name every part, in order, joined by + — that line is three parts because 1.0.0 has three, and a release with four needs a fourth name on it. Copying the line as written for an image with more parts is the failure this section exists to prevent: it succeeds, and leaves a short ISO.

Do not use a wildcard instead: copy takes wildcard sources in directory order, which is not guaranteed to be sorted, and parts joined out of order give you a file of the right size that is quietly corrupt.

/b is not optional. Without it copy runs in text mode and stops at the first 0x1A byte, which in this image is a few hundred KB in — you get a short file, no error message, and a stick that does not boot.

If copy /b gives trouble, PowerShell can do the join instead, and it has no text mode to fall into:

$out = [System.IO.File]::Create((Join-Path $PWD 'SynapseOS-<ver>-x86_64.iso'))
Get-ChildItem 'SynapseOS-<ver>-x86_64.iso.part*' | Sort-Object Name | ForEach-Object {
  $in = [System.IO.File]::OpenRead($_.FullName); $in.CopyTo($out); $in.Close()
}
$out.Close()

Check the result with the same command as any other download — a bad join is the most common way a split download goes wrong, and every symptom of it looks like a broken ISO.

Check who built it

The checksum proves the download arrived whole. It does not prove where the image came from: it is served from the same place as the ISO, so anything that could alter one could alter the other. The signature answers that.

curl -O https://soslinux.org/synapseos-release-key.asc
gpg --import synapseos-release-key.asc

gpg --verify SynapseOS-<ver>-x86_64.iso.asc SynapseOS-<ver>-x86_64.iso

A good signature names the key it matched; check that fingerprint against:

6548 9EF5 C20D 0BD9 4211  472B ED33 6DB7 952B 609E

That same fingerprint is committed in the source repository as archiso/release-key.fingerprint — a different host, run by somebody else, than the one that served you the image. Comparing the two is what makes the check worth making.

GnuPG also says the key is not certified with a trusted signature. That is expected and is not a failure — it means you have not told GnuPG you trust this key, only that the signature matches it. Comparing the fingerprint is what closes that gap.

Releases from 0.2.9.5 onward are signed; earlier ones are not. On Windows, Gpg4win gives you the same three commands in PowerShell.

3. Write it to the stick. Any of these work:

Writing a stick erases it — the image goes on as a raw disk, not as a file. Ventoy is the exception.

Then boot the stick from your firmware's boot menu, usually F12, F11, Esc or Del at power-on. Secure Boot has to be off, or SynapseOS enrolled — see Secure Boot.

The image carries no AI model

The ISO carries no AI model, since 0.2.8. That is about 4 GB off the download, and it means the installer asks which model you want instead:

It is asked on every preset except Minimal, needs a network, and runs near the end of the install so nothing else is stuck behind a 4 GB progress bar. A failed download warns rather than failing the install — the machine boots either way, with the same end state as choosing None.

On the live ISO itself there is no model, so synapd starts in shell-assist mode with nothing to load and syn status reports "model ✗ not installed". That is expected on live media, not a fault to chase. Building with archiso/build.sh --with-model puts one back on the image.

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

Picking a language

It is the first question the image asks. The bootloader carries a Language submenu — fifteen entries, each written in its own language — and choosing one boots with the answer already given. Take the plain entry instead and the live image opens on the same list as its own first screen.

One answer sets all of it: the console keymap, the desktop keyboard layout, the locale, the console font, the font packs that get installed, the language synsh speaks, and the installer's own words. The installer does not ask again twenty minutes later — it reads the answer back.

Both keyboard halves are set, which is not the same as one. KEYMAP= names a file loadkeys must find and xkb_layout names a layout xkbcommon must compile, and they disagree on four of the fifteen rows — Swedish is sv-latin1 to the console and se to the desktop. They can still be changed separately afterwards.

The installer speaks fourteen languages: English, Deutsch, Français, Español, Português, Italiano, Nederlands, Polski, Русский, 日本語, 中文, 한국어, हिन्दी and العربية. Both installers do — the graphical one draws the same sentences as the text one, from the same catalog, and its own Language page re-translates the window in place if the image booted in the wrong one.

Japanese, Chinese, Korean, Arabic and Hindi cannot be drawn on a text console. A Linux virtual terminal holds at most 512 glyphs and does no text shaping, so the text installer keeps English prose for those five and says so in one line. Everything else about the choice still applies — the locale, both keyboards, the fonts and the installed system are the ones asked for — and the graphical installer and the installed desktop draw all thirteen properly.

What is never translated: the answer keys. [Y/n], [y/N] and typing yes to confirm a disk wipe stay those letters in every language, because the installer compares against them.

Choosing what to install

Four presets:

Custom is every package

Since 0.2.9 there is no unconditional SynapseOS package. Eleven of them used to be installed whatever you answered — the package manager, the file manager, the terminal, Settings, Disks, the editor, syn, syn-model, syn-firstboot, syn-confine and fetch — and Custom could not decline any of them. All twenty-five are checkboxes on one page now:

  SynapseOS packages — everything the system is made of

  [x]  1) SYNAPSE UI    the desktop     [x] 14) Models        fetch AI models
  [x]  2) synapd        the AI daemon   [x] 15) First boot    first-run setup
  [x]  3) synsh         the AI shell    [x] 16) Sandbox       Landlock jail
  [x]  4) synguard      security watch  [x] 17) About OS      the OS readout
  [x]  5) synnet        network policy  [x] 18) Arcade        pads + overlay
  [x]  6) Software      package manager [x] 19) cliamp        music player
  [x]  7) Files         file manager    [x] 20) Arsenal       BlackArch tools
  [x]  8) Terminal      the terminal    [x] 21) Chibi         voice companion
  [x]  9) Settings      system settings [x] 22) Vibe          AI coding help
  [x] 10) Disks         disks + format  [x] 23) Wallpapers    animated, 317MB
  [x] 11) Editor        the text editor [ ] 24) Nexus Chat    chat (+Firefox)
  [x] 12) Updates       receives fixes  [ ] 25) TEPRIS        game (+Firefox)
  [x] 13) syn           top-level CLI

  Toggle [numbers, 'all', 'none', Enter = accept]:

Type the numbers you want to flip, all or none to sweep the page, and Enter to accept. The same pages appear as checkbox lists in the graphical installer.

What you cannot switch off is what something else you kept depends on. Those are turned back on and named before anything is installed:

A checkbox that silently un-ticks itself would be worse than one that was never offered, so the installer prints what it re-ticked and why, before the summary.

Two deselections it stops to warn about, because both cost something you only notice weeks later:

• syn-update off — the machine has no way to receive another SynapseOS package. Fixing that later means installing it by hand from the ISO.
• synui off — SynapseUI is no longer offered on the Desktop page; the answers are KDE, GNOME or no GUI. A profile that asks for both desktop = "synui" and comp.synui = false is refused by name rather than quietly resolved.

Ordinary software

Five more pages, all of it from the Arch repositories and none of it ours:

Firefox is ticked by default on every preset except Minimal. Before 0.2.9 an installed SynapseOS arrived with no web browser at all unless you picked Full, where Nexus Chat happened to pull one in as a dependency.

Steam is not on those pages — it is one of the y/n options below, because it is the only item that turns on a second architecture ([multilib] and the lib32 tree).

The shelf installs last, in its own transaction, after the system is complete. A failure there warns and retries one package at a time, so a name that moved upstream fails alone and is named, instead of taking every SynapseOS package down with it. Anything that did not land is one synpkg install <name> away.

Docker and Syncthing are the two whose units are enabled for you; everything else is inert until you open it.

The y/n options

Not packages — a repository, an architecture or a service. Each is asked one at a time because each has a consequence too long for a checkbox:

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 has been in every release since 0.2.5. 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.

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

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

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

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.