Wiki
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: 1.0. Actively developed and daily-driven by the author, and ready for you to do the same. A rolling release — an installed machine keeps taking updates through
syn-update.
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.