Settings

Settings

syn-settings is SynapseOS's settings app — the system half of the desktop's configuration. It is one C binary plus a quickshell window, in the same shape as synfiles and synpkg: the binary does the work and prints records, the window only renders them.

Front-end	Command
The window	Settings in the start menu, or syn-settings gui [pane]
Command line	syn-settings --rec <pane> to read, syn-settings set … to change

Settings is not the control panel. Super+C is the compositor's settings — borders, gaps, animations, blur, focus behaviour, every keybinding — changed live while you watch a window change. This is the other half: the things that belong to the system rather than to synui, and the ones that talk to localectl, timedatectl, bootctl, rfkill and nmcli.

---

The panes

Pane	What it covers
Display	Connectors, and what each can do: the kernel's view of a monitor beside what the compositor is actually driving. Set a mode, re-probe a connector the kernel has lost
Region	Keyboard layout and locale — the console keymap and the desktop's XKB layout are separate rows, because they are separate settings
Date & Time	Zone, network time, and how the desktop writes the time: 12- or 24-hour, seconds in the bar clock, and the date order
Network	Interfaces, radios, whether the firewall is up, and which container bridges it trusts; bring an interface up or down
Bluetooth	Adapter, radio blocks, and what is paired
Power	Sleep-critical units, sleep hooks, and the last suspend — what would stop this machine sleeping, before you find out by closing the lid
Kernel	Every kernel on offer, which are installed, which one runs, and which one boots. See Kernels
Apps	The default application for each role — and which file decided it
System	The machine's name, and where configuration actually lives

Two rules that shape it

It reports what the system reports. Every pane reads the real source when it opens — localectl, timedatectl, wlr-randr, rfkill, bootctl, /etc/fstab — rather than a cache of its own. A settings app that keeps its own copy is confidently wrong about a machine that changed under it, which is the single most annoying thing a settings app can be.

Every row says which file decided it. A default application you picked and one that came from a distribution fallback read identically everywhere else on a Linux desktop. Here the Apps pane names the file, so "why does this open in that" is a question with an answer on screen.

Kernels

The Kernel pane installs and removes kernels (through synpkg) and switches which one boots, on all three bootloaders SynapseOS can install: limine, systemd-boot and GRUB.

It distinguishes three states that look identical in a package list:

State	Means
installed	The package is on the disk
bootable	A boot entry exists and an initramfs was actually built for it
running	It is the kernel you are using right now

Installed is not bootable. A kernel package that never had an initramfs generated, or that no boot entry names, is a kernel you cannot select at the boot menu — and a package list cannot tell you that.

syn-settings --rec kernel                       # what is installed, bootable, running
syn-settings pkg install linux-lts              # add one
syn-settings boot linux-lts --confirm           # make it BOOTABLE
syn-settings default linux-lts --confirm        # make it the one that boots

boot and default refuse to do anything without --confirm, and boot needs root outright — it goes through pkexec, so it asks for admin authentication.

Changing the boot kernel is the one setting here that can stop a machine starting. Keep a kernel you know boots installed and bootable, and change the default only from a system you can get back into.

From a script

Everything the window does has a command-line half. --rec prints TSV — a header line, then rows — which is meant to be piped:

syn-settings --rec region | column -t -s$'\t'
syn-settings --rec apps                  # each role, its app, and which file chose it
syn-settings choices date-format         # what a setting can be set TO, with examples
syn-settings apps browser                # every application that could take a role

Writing:

syn-settings set xkb us intl             # desktop keyboard layout
syn-settings set keymap uk               # console keymap — a different setting
syn-settings set timezone Europe/London
syn-settings set ntp on
syn-settings set time-format 24          # how the desktop writes the time
syn-settings set hostname loft           # the machine's name (see below)
syn-settings set app browser firefox     # a .desktop name; a command for `terminal`
syn-settings unit restart synapd         # enable|disable|start|stop|restart
syn-settings mode DP-1 1920x1080@60      # via wlr-randr

-n / --dry-run prints what would be run and changes nothing. Exit status is 0 success, 1 failure, 2 refused (a bad argument) — so a script can tell "it did not work" from "you asked for something that is not a thing".

Most writes are performed by a systemd tool that does its own polkit check; the binary is not setuid and ships no polkit policy of its own.

Naming the machine

Every SynapseOS install answers to synapse. Put two of them on one network and Avahi renames one synapse-2.local — with no say in which, and no promise the suffix survives a reboot, so the .local address stops being something anybody can rely on. Renaming used to be a hostnamectl one-liner, which is to say it was not in the settings application at all.

The identity row on the System pane does it, and so does the command line:

syn-settings set hostname loft

The write goes through hostnamectl, which does its own polkit check — the same design every writing row here follows, so this binary stays not-setuid with no policy of its own. The name is validated here first, and more narrowly than most values (letters, digits, hyphen and dot; no leading or trailing punctuation; 63 characters), because a refusal here can say what was wrong with what you typed where systemd can only say hostnamectl exited 1.

Where the settings actually live

The System pane answers this directly, and it is worth knowing the shape:

Layer	Holds
/etc/synui/synuirc	The system-wide compositor defaults
~/.config/synui/synuirc	Your compositor config; overrides the above
~/.config/synui/*.state	What a panel changed live — theme, font, dock, filters. These override synuirc, by design
localectl / timedatectl	Region and time — systemd's own state, not a SynapseOS file

The .state files winning over synuirc surprises people once: a value you edited in synuirc and a value you changed in a panel are not the same setting in the same place, and the panel's copy is the newer statement of intent. Delete the .state file to hand control back to synuirc.

See also

Commands · The Desktop · Software · Keybindings · Troubleshooting