Home

SynapseOS Wiki

Where the kernel thinks.

An Arch-based operating system with a local LLM wired into the system layer — a shell, a Wayland compositor, a security monitor, a network policy daemon and a kernel module that all talk to one inference daemon over a Unix socket.

This wiki is the operator's manual: how to install it, how to build it, how to cut a release, and — most usefully — the failure modes we have already hit so you don't have to rediscover them. For the project pitch and the component overview, see the README.

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.

Upgrading from an ISO older than 0.2.3? Your SynapseOS components have never received an update — pacman -Syu only ever covered the Arch half, and it failed silently. Updating explains what happened and how syn-update fixes it.

---

Start here

Page	What it covers
Installation	Boot the ISO, install to disk, try it in QEMU
Updating	syn-update — keeping an installed system current. Not the same as pacman -Syu
Keybindings	Every synui shortcut
Commands	The syn* command-line surface, and the privileged desktop actions
Nix	The optional Nix + Home Manager layer, and installing from a profile
Gaming	Game mode, synui-game-run, MangoHud, Wine
Architecture	How the pieces fit and how they talk
Secure Boot	Enrolling keys, Setup Mode, module signature policy
Building and Packaging	Build from source; the makepkg traps
Cutting an ISO Release	The release pipeline, end to end
Development Notes	Engineering lessons — the silent failures, and the rules they left
Troubleshooting	Something's broken — symptom-first fixes

Making it yours

Page	What it covers
The Desktop	The bar, the mixer, desktop widgets, desktop icons, themes
Wallpapers	The picker, per-monitor wallpapers, Steam Workshop via synui-wpengine
Window Effects	Glass, blur, shadows, rounded corners, the CRT pass
Cursor Themes	synui-cursor — installing themes from any archive
Sound Themes	synui-sound — event sounds, off by default

Components

Page	What it covers
synapd	The LLM daemon; GPU offload; the wire protocol
synui	The wlroots compositor: layouts, dock, filters, screenshots
synguard and synapse_kmod	Syscall telemetry, threat scoring, worm/keylogger detection
synsh	The AI-native shell

Apps

Page	What it covers
Vibe	Local AI coding assistant — an agentic tool-calling loop on synapd's model
Chibi	Voice companion with a security-sentinel aspect over synguard's feed
TEPRIS	The bundled block game
Nexus P2P	Peer-to-peer chat

---

The one paragraph that saves the most time

Almost every hard bug in this project's history has been a silent failure — something that kept exiting 0 while doing nothing. A stale DKMS module that dkms status cheerfully called "installed". Hand-copied .so files in /usr/lib that shadowed the real ones. A /etc systemd unit shadowing the hardened packaged one. A GPU layer count that was hardcoded and never read the GPU. When something here "works but doesn't", do not trust the status command — go look at the running process: /proc/<pid>/maps, systemctl show -p FragmentPath, modinfo's vermagic against uname -r. Troubleshooting is a catalogue of these.