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: beta (0.3.x). Actively developed and daily-driven by the author, and ready for you to do the same. It still moves fast.

---

Start here

Page	What it covers
Installation	Boot the ISO, install to disk, try it in QEMU
Welcome Guide	Super+Escape — the seven pages a new desktop opens with, and how to turn them off
Updating	syn-update — keeping an installed system current. Not the same as a plain Arch upgrade
Software	synpkg — installing things, from the repositories, the AUR, Flathub or BlackArch
Files	synfiles — the file manager a folder opens in: trash, undo, split view, properties
Calendar	syn-cal — your calendars, synced both ways: CalDAV, Google, Microsoft 365
Settings	syn-settings — displays, region, date and time, network, Bluetooth, power, kernels, default apps
Editor	syn-edit — the text editor: a modal one in a terminal, an ordinary one in a window, and a scriptable one with neither
Studio	synstudio — the photo darkroom and video editor: RAW develop, masks, looks, and a graded timeline
Terminal	syntty — the default terminal: tabs, images, prompt marks, and no GL
Keybindings	Every synui shortcut
Speech and dictation	syn-speak — the desktop out loud: the focused window announced, the selection read, and speech typed back
Commands	The syn* command-line surface, and the privileged desktop actions
DaVinci Resolve	Installing it, the OpenCL trap, and footage the free edition can read
Nix	The optional Nix + Home Manager layer, and installing from a profile
Gaming	Game mode, syn game, MangoHud, GeForce NOW, controllers, Proton
Big Screen	syn-arcade — the ten-foot interface for a television, and the music on it
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 two bars, the mixer, desktop widgets, desktop icons, themes and glass
Configuration	Every synuirc key the compositor accepts — keyboard, pointer, windows, blur, animation, effects
The Dock	The icon row — edges, pins, the clock/apps/power cells, its right-click menu
Bar Plugins	Third-party bar widgets, in Omarchy's plugin format
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	The desktop assistant — a chat window and a terminal REPL, with the run of the desktop
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.