synapd

synapd

The local LLM inference daemon (llama.cpp). It owns the model — every other component reaches it over a Unix socket rather than linking llama.cpp itself. See Architecture for the protocol.

systemctl status synapd

---

The model

The default ISO embeds Mistral 7B Instruct (Q4_K_M, ~4.1 GB), so the AI is live on first boot with nothing to configure. ISOs built --no-model are ~4 GB smaller and fetch it on first boot via syn-firstboot.

To drop one in by hand:

cp your-model.gguf /var/lib/synapd/models/synapse.gguf
systemctl restart synapd

Any GGUF that llama.cpp can load works. Mistral 7B Instruct is what the prompts are tuned against — swapping models may need prompt work.

---

GPU offload

The llama.cpp libraries synapd links are packaged per backend; each GPU build provides + conflicts synapse-llama, so pacman refuses a silent downgrade to the CPU build. That design exists because of the bug below.

Package	Hardware	Backend	Notes
synapse-llama	any	CPU	the default; what the ISO ships
synapse-llama-cuda	NVIDIA	CUDA	hard-links libcuda.so.1 — cannot start without the driver, so never on the ISO
synapse-llama-vulkan	AMD / Intel	Vulkan	links only the Vulkan loader; one build runs on any AMD (GCN/RDNA/APU) or Intel GPU, and loads even with no GPU (falls back to CPU)

syn-install swaps in the right one for the detected card (-cuda on NVIDIA, -vulkan on AMD/Intel); switch by hand any time with the AI backend row or synui-ai-backend gpu. Vulkan is the portable AMD/Intel choice — no per-architecture compile and only the mesa ICD at runtime — and is competitive with ROCm for token generation. ROCm/HIP stays an opt-in for a known-supported AMD card: build.sh --gpu=rocm.

Verify it. Never assume it.

# NVIDIA / CUDA:
grep -c nvidia /proc/$(pidof synapd)/maps               # 0 = you are on the CPU
# AMD / Intel / Vulkan:
grep -Ec 'libvulkan|radv|amdgpu|libggml-vulkan' /proc/$(pidof synapd)/maps

A log line claiming GPU offload is not evidence. Check the mapped libraries of the running process (needs sudo — synapd runs as its own user).

The GPU saga (resolved 2026-07-11, 37ce3da) — 33/33 layers on CUDA0

synapd ran on the CPU for the entire life of the project while appearing to be on the GPU. Rebuilding CUDA alone would not have fixed it. There were three stacked silent failures:

1. Unowned .so files in /usr/lib — hand-cp'd at some point, owned by no package, silently winning the ld.so cache over the real build.
2. ld.so.conf pointed at $HOME — so even the right libraries resolved from the wrong place.
3. detect_gpu_layers() returned a hardcoded 28, derived from an lspci probe rather than from the GPU. This is why it stayed invisible: the number looked plausible, so nothing ever contradicted the assumption.

The lesson is #3. A plausible hardcoded value is worse than a crash — it produces a system that lies to you consistently.

Building CUDA

llama.cpp pinned at b8272, with a CCCL 3.4 cub patch (CUDA 13 broke the API). Verified clean with gcc 16 + nvcc 13.3.

The ISO ships a CPU build on purpose. A CUDA-linked synapd needs libcuda.so.1, which doesn't exist on a machine with no NVIDIA driver — it would fail to start on most hardware. build.sh --no-gpu (the ISO default) builds CPU-only with GGML_NATIVE=OFF so it runs on baseline x86-64. See Building and Packaging.

---

VRAM and game mode

Game mode (Super+G) stops synapd to hand its VRAM to the game. Two bugs worth knowing, both silent:

• The stop failed on polkit — synapd is a system unit and the stop was a fire-and-forget spawn, so it silently did nothing and synapd kept the VRAM. Now uses sudo -n with a dedicated /etc/sudoers.d/synapd-gamemode.
• Stopping synapd also killed synnet, which has Requires=synapd.

Per-process VRAM is visible in the task manager (Ctrl+Alt+Delete), which reads NVML via dlopen — no CUDA headers needed at build time.

---

Switching the inference device (GPU / CPU / off)

The control panel's (and Super+Escape menu's) "AI backend" row cycles synapd between GPU → CPU → off. It runs synui-ai-backend, which rewrites synapd's --gpu-layers via a systemd drop-in, restarts it, and records the choice in /run/synapd/backend (which the row reads back for its label):

synui-ai-backend gpu      # --gpu-layers -1  (auto-detect; offload to the GPU)
synui-ai-backend cpu      # --gpu-layers 0   (force CPU-only)
synui-ai-backend off      # stop synapd — frees all its RAM/VRAM
synui-ai-backend toggle   # cycle to the next state
synui-ai-backend status   # print the current device

Same privilege story as game mode: the compositor runs as the session user with no polkit agent, so the helper self-escalates with sudo -n for the mutating verbs, allowed by a scoped /etc/sudoers.d/synapd-backend rule. Without it the row was silently stuck reading "auto" — nothing to select. (status stays unprivileged; it only reads a world-readable file.)

---

Talking to synapd directly

chibi (the assistant) has an optional synapd backend in llm_client.py that talks straight to the Unix socket instead of an HTTP LLM server — verified live. It's the reference example of writing a synapd client.

See also: Architecture, Troubleshooting.