The service & where things live

Everything OS-specific in one place - the per-user service (launchd, systemd, or a Scheduled Task), its native controls and logs, the detached updater behind automatic updates, and every path Seamless touches.

The installer registers seamlessd as a per-user service, so the daemon survives reboots without you supervising it. It runs as your user, not root: it reads your config, writes your files, and should die with your login session, not the machine.

By default there is one instance per machine: port 8081, data dir ~/.seamless - one daemon, one database, one set of files. Both are config keys, not fixed facts: set addr: and data_dir: in ~/.config/seamless/seamless.yaml (or the SEAMLESS_ADDR / SEAMLESS_DATA_DIR env overrides) and restart the service. The config is the single source of truth for the bind address - the installer and the Makefile both read the port back out of it, so their health checks follow your change rather than assuming 8081, and nothing bakes the address into the service itself.

One instance per machine is the default, not a law. Several devices can share one daemon: the server keeps the service, the database and the corpus, and every other machine installs with role: client plus server_url, which runs no daemon and registers no service at all (seamlessd serve refuses on a client outright). Everything below describes the server's install; Share one daemon across a LAN is the setup, and the tradeoffs.

Control it from anywhere

Whatever the platform, one set of verbs controls the service - they resolve your OS's service manager for you:

seamlessd start       # start | stop | restart | status
make start            # the same, from a clone (start | stop | restart | status)

These act on the already-installed service and print a hint if it was never installed. The platform-native commands below are what they wrap - you need them only when you want to talk to the service manager directly.

The service on your OS

launchctl print gui/$(id -u)/org.thereisnospoon.seamless        # state
launchctl kickstart -k gui/$(id -u)/org.thereisnospoon.seamless # restart
launchctl bootout gui/$(id -u)/org.thereisnospoon.seamless      # stop

systemctl --user status seamless      # state, pid, last exit
journalctl --user -u seamless -f      # follow the log
systemctl --user restart seamless
systemctl --user stop seamless

Get-ScheduledTask Seamless | Get-ScheduledTaskInfo   # state, last run, last result
Get-Content ~/.seamless/seamlessd.log -Wait          # follow the log
Restart-ScheduledTask Seamless                        # stop + start
Stop-ScheduledTask Seamless                           # stop (it restarts at next logon)

The updater on your OS

On an install the installer made, the daemon installs new releases by itself (Automatic updates covers which installs, and when). It never installs anything in-process. It starts the updater, seamlessd update --auto, which verifies the new release and runs that release's own installer, and the installer restarts the service. So the daemon starts the updater where stopping the service cannot reach it, which is a different place on each OS.

The updater runs the seamlessd on disk and refuses unless that binary is the release the daemon is updating from. It also refuses to run inside the service's own process tree. It holds ~/.seamless/update/update.lock for its whole run, so only one update runs at a time, and records itself in ~/.seamless/update/attempt.json. Every step, and the installer's output, goes to ~/.seamless/update/logs/<attempt>.log.

pgrep -fl 'seamlessd update --auto'   # an update in progress

systemctl --user list-units 'seamless-update-*'   # an update in progress
journalctl --user -u 'seamless-update-*'          # what it printed, if it refused before its log opened

Get-CimInstance Win32_Process -Filter "Name = 'seamlessd.exe'" | Where-Object CommandLine -like '*update --auto*'   # an update in progress
Get-ScheduledTask -TaskName 'SeamlessUpdate-*'                                                                   # only once the fallback has run

When an update goes wrong

Every attempt leaves a record. seamlessd doctor (its updates row) and seamlessd update --check print the last attempt with the updater's own error, its log and the backup it took. An automatic update failed walks through the outcomes. What the service manager can tell you:

• An update that never started is recorded at the spawn stage, and the daemon tries again after a backoff. When the daemon could not start the updater, its log says why (could not start the updater). On Linux the reason is one of systemd-run is not installed, the systemd user manager is unreachable, this attempt's unit already exists, the seamlessd binary is missing or not executable and the updater could not be executed. On Windows the error names why the detached process failed and why the update task failed. When the updater started but refused before it recorded anything, it said why on its standard error: in ~/.seamless/seamlessd.log on macOS, and in journalctl --user -u 'seamless-update-*' on Linux. On Windows that output goes nowhere.
• An update the updater's gates refused names the owner's action in doctor's updates row, and every retry is refused the same way until you act. A release installed without a restart (the seamlessd on disk is not the one the daemon runs), or an install that no longer looks installer-made, needs seamlessd restart. An updater that could not make sure it runs outside the service needs seamlessd update, run by hand from a terminal.
• An updater that hangs is stopped by a limit: the installer's own 15-minute timeout on every OS, the unit's 30 minutes on Linux, and the update task's hour on Windows. You can also stop it by hand: on Linux with systemctl --user stop 'seamless-update-*', and on macOS and Windows by ending the seamlessd update --auto process. The OS releases the update lock however the updater dies, and the daemon settles the attempt from the release that is running. An attempt stopped while the old release still runs counts as interrupted and is tried again after a backoff. That run reinstalls the new release and confirms it, or rolls back.
• A service left down by an update that could not be rolled back cleanly: the attempt's error carries the updater's recovery steps. Reinstalling the release you had is the installer pinned to it: curl -fsSL https://thereisnospoon.org/install | SEAMLESS_VERSION=<version> sh, or $env:SEAMLESS_VERSION='<version>'; irm https://thereisnospoon.org/install.ps1 | iex on Windows. Then run seamlessd doctor.
• Putting the whole instance back from the pre-update backup is a restore, and seamlessd import restores only into an empty data directory (into a populated one it merges). Run seamlessd stop, then move ~/.seamless aside (to ~/.seamless.broken, say; the backup moves with it), then run seamlessd import --from ~/.seamless.broken/backups/pre-update-v<old>-<time>.tar.gz, then seamlessd start.

Where things live

Every ~ path resolves under %USERPROFILE% on Windows - the daemon searches the same relative locations on every OS.

Removing the service by hand

Update & uninstall covers seamlessd uninstall, which removes the service along with everything else, including what the updater leaves behind. On Linux it first stops any update unit still loaded, so an updater caught mid-update cannot restart the service it is removing. On Windows it deletes your SeamlessUpdate-<SID> task. On macOS the updater leaves nothing to remove. For a bare binary you never registered a service for, or a machine you are cleaning by hand, the native teardown is:

launchctl bootout gui/$(id -u)/org.thereisnospoon.seamless   # macOS
systemctl --user stop 'seamless-update-*'                    # Linux: an update still running
systemctl --user disable --now seamless                      # Linux

Unregister-ScheduledTask -TaskName Seamless                  # Windows
Unregister-ScheduledTask -TaskName "SeamlessUpdate-$([Security.Principal.WindowsIdentity]::GetCurrent().User.Value)"   # Windows: the update task, if it exists