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.1.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.

---

Start here

Page	What it covers
Installation	Boot the ISO, install to disk, try it in QEMU
Keybindings	Every synui shortcut
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, desktop widgets, desktop icons, themes
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

---

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.