Updating

syn-update keeps an installed SynapseOS current with the project's own components — synui, synapd, synguard and the rest. It is separate from synpkg upgrade, which updates Arch.

You need both. They cover different halves of the system.

Quick start

syn-update check     # read-only: fetch and show what would change
syn-update apply     # rebuild the changed components and install them
syn-update status    # source revision and installed versions

check is the default, so bare syn-update is safe. It is also available as syn update.

It asks for your password once. sudo's timestamp is five minutes and a full rebuild is much longer, so an apply used to authenticate and then ask again three or four times at unpredictable moments — build-all.sh ends every component with a pacman -U, and the credential expired mid-run, leaving the build stopped at a prompt long after anyone was still watching it. One password now, with a keep-alive behind it.

There is a GUI — SynapseOS Updates in the start menu. It owns the read-only half and hands apply to a terminal window, deliberately: apply needs to run sudo pacman -U partway through a build, and sudo with no controlling terminal cannot prompt for a password. An in-window apply would fail at the install step, minutes into a build.

Note the start menu has two update entries, and they are not the same thing. Update System is Arch. SynapseOS Updates is this. Conflating them is how a machine ends up fully patched on the Arch side while its compositor sits hundreds of releases behind.

Being told, instead of remembering to look

A systemd user timer runs syn-update ping — the same check, quietly, with the answer written to a small file instead of printed as a report — and the bar grows an indicator showing how many updates are waiting. Click it and the Updates window opens. It is invisible when the machine is current: a row that reads "0 updates" all day is a row nobody reads on the day it says something else.

syn-update ping --every 6h    # 30m, 12h, 1d, 1week — systemd's own syntax
syn-update ping --off         # stop checking
syn-update ping --on          # start again
syn-update ping               # check right now

It is on by default, every six hours, three minutes after login and with ten minutes of jitter so that every SynapseOS box does not fetch on the same tick.

⚠ Two switches, and neither is a copy of the other. ping --off stops the machine asking upstream — that is about network traffic. Hiding the bar indicator is furniture, and lives with the rest of the bar's furniture: right-click the bar ▸ Update notifier, per monitor, beside the clock and the tray. You can have the checking on and the icon hidden, or the icon shown and the checking off (it keeps whatever it last saw).

The interval is stored as a systemd drop-in under ~/.config/systemd/user, never in the unit the package ships. /usr/lib belongs to the package and every upgrade replaces it — and this particular package is the updater, so an interval written there would quietly revert to six hours the next time syn-update updated itself.

A check that fails says so. If the source tree is not usable — most often left root-owned by an older run — ping refuses rather than reaching for a password it cannot ask for under a timer, and records the refusal. The indicator then shows ! and the tooltip explains, instead of showing a stale count and implying the machine is up to date. Run syn-update check once in a terminal to clear it.

How it works

syn-update clones the project's git repository to /var/lib/synapse-src, compares each component's pkgver/pkgrel at the remote revision against what is installed, and rebuilds only what changed. Builds go through makepkg, so components are compiled on your machine rather than downloaded as binaries.

After installing, it republishes the built packages into the local repository at /var/cache/synapseos and rebuilds that repository's index. This matters: without it, a later pacman -S synui to repair an install would happily fetch the stale version the ISO shipped.

The source tree is chowned to the user who invoked the command, because makepkg refuses to run as root.

Only signed commits are built

Every commit syn-update builds must be signed with the SynapseOS update key. The key ships inside the syn-update package, in /usr/share/syn-update/keys/, and is never taken from the downloaded source. A copy of the repository from GitHub or from a mirror is checked the same way.

syn-update checks every new commit, oldest first. If some are not signed, it builds up to the last signed one and leaves the rest out, and syn-update check says so:

warn  2 newer commit(s) on origin/main are not signed by a SynapseOS update key, and are not built:
warn    the first is 1a2b3c4 <its subject>

If none of them is signed, it builds nothing. The key's fingerprint is in SECURITY.md.

Options

Requirements

Because it builds from source, syn-update needs a toolchain. It depends on bash, git, base-devel, pacman, sudo and gnupg, all of which pacman resolves from core — roughly 17 packages, ~118 MiB on a system that has none of them.

cmake and meson are deliberately not hard dependencies. makepkg -s pulls each component's own makedepends on demand, so you only pay for what you actually build. Hard-depending on cmake would add ~150 MiB for a component syn-update does not update anyway.

What it does not update

Some components are on the ISO but are not rebuilt this way. syn-update reports these rather than skipping them silently — a component quietly frozen forever is the exact bug this tool exists to fix.

These move with an ISO upgrade instead.

A component that is new since you installed is ADDED, not skipped. That is what makes a suite work: synfiles, synpkg, syn-settings, syn-disks, syn-edit, syn-confine, syn-arcade, syntty and cliamp all arrived after some installed systems were built, and a machine that only ever updated what it already had would never see any of them.

⚠ Adopting a brand-new component takes two applies. syn-update computes its build set from the component list in the syn-update that is installed, so the first apply updates syn-update itself and the second one sees the new component and offers it. A check that shows an update and then says "everything is already current" is that, not a bug — run it again.

fetch and synapse-wallpapers were the other half of this problem, in the opposite direction: both are in packages.x86_64, so they were on every installed machine and updatable on none, with nothing saying so. They are covered now.

Adding software is a louder act than updating it, so new components are listed in their own section of syn-update check rather than mixed in with the upgrades.

Two are deliberately excluded from that, and syn-update names them rather than skipping in silence:

Both are still updated when present; they are only never introduced.

Why this exists

Every system installed from an ISO before 0.2.3 was given a package repository that could never change:

[synapseos]
SigLevel = Optional TrustAll
Server = file:///var/cache/synapseos

That directory is copied off the ISO at install time and nothing ever writes to it again. So pacman -Syu faithfully upgraded all of Arch and could never see a newer synui, synapd or synguard. An installed SynapseOS was frozen at whatever ISO installed it — and, worst of all, with no error to notice. The update command succeeded, reported nothing to do for the SynapseOS packages, and was wrong.

syn-update closes that hole, and it lists itself among the components it can update — an updater that cannot update itself would need an OS reinstall to fix, which is the dead end being removed.

Troubleshooting

syn-update apply fails at the install step with a sudo error. apply runs sudo pacman -U mid-build and needs a terminal to prompt on. Run it from a terminal, not from a launcher or a script with no tty. The GUI does this for you.

It reports a component as unsupported. That is intentional and not an error — see the table above. Those components come with an ISO upgrade.

pacman offers to downgrade a SynapseOS package after an update. That was a real bug in syn-update 0.1.0-6 and earlier, where the local repository kept advertising versions older than what was installed. Update syn-update itself first, then re-run.

check says newer commits are not signed and are not built. The project has pushed commits without its signature. Nothing past them is built until they are signed; the next check after that picks them up. Nothing needs doing on your machine.

nothing on origin/main is signed by a SynapseOS update key — refusing to build it. The repository syn-update fetched is not one the installed key signs — usually SYN_UPDATE_REPO pointing at a fork. To build a fork anyway, run with SYN_UPDATE_ALLOW_UNSIGNED=1.

Nothing happens and no error appears. Check syn-update status for the source revision it is actually tracking. If the tree at /var/lib/synapse-src has local modifications, apply will refuse to clobber them without --force.

See also: Commands · Installation · Building and Packaging · Cutting an ISO Release