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 and their addresses — a MAC row per interface and the IP addresses it holds, with one gateway and one nameserver row — plus radios, whether the firewall is up, and which container bridges it trusts; bring an interface up or down. See The Network pane
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.

The Network pane

Four kinds of row, in this order.

device — every interface NetworkManager knows about, its type, its state and the connection on it. Selecting one offers up and down; loopback is the exception, because there is nothing there to switch.

mac — the hardware address of each interface. This is the one you need in order to wake this machine from another: a magic packet is addressed to a hardware address, not an IP, so syn-remote wake on the far machine needs what this row prints. Only a wired card can be woken that way, and the row for a Wi-Fi card says so rather than leaving you to arm something that cannot work — a Wi-Fi card does not stay associated through a suspend. A bridge is named as a bridge, so a docker0 or br-… row is not mistaken for a network card.

ip — the addresses each interface holds right now, IPv4 first, followed by one gateway row and one nameservers row. Those two are one row each rather than one per interface: every device carries the fields and only the one holding the default route fills them in, so a row per interface would be a column of blanks around the answer.

⚠ The fe80:: link-local address that every interface always has is left out. It is as long as a real address and cannot reach anything without an interface named alongside it, so listing it widens the row to say nothing. An interface whose only IPv6 address is link-local shows no IPv6 address here.

firewall — three separate things, because they answer differently:

Row	What it is
input filtering	The preference in /etc/synnet/firewall, and the state synnet last published to /run/synnet/firewall.state
container links	The bridges named in /etc/synnet/trusted-ifaces. A Waydroid or libvirt guest asks for its address from 0.0.0.0, which a default-drop policy eats — the symptom is "the container has no internet" and nothing says firewall. Add one with sudo synnet --trust-if <iface>
rebuilt	Only when it has happened: how many times the ruleset has gone missing and been re-asserted since synnet started
synnet.service	The daemon that applies all of the above. Rules outlive it, so a stopped synnet leaves the last ruleset in place and stops maintaining it

⚠ None of this reads the kernel. It reports what synnet asserted, which is not the same claim as what nftables currently holds.

Nothing in the mac or ip rows is editable. An address is read, not set — NetworkManager owns setting it.

Addresses are hidden until you ask

Every mac and ip value reads ••:••:••:••:••:•• until you ask for it, so a screenshot or a stream does not carry them. The Bluetooth pane's adapter address and every paired device's are masked the same way.

Reveal addresses, at the top right of the window, shows them. The button reads Hide addresses while they are showing, and moving to another pane hides them again.

The command line does the same with a flag:

syn-settings --rec network              # masked
syn-settings --rec network --reveal     # in full

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