Background jobs
Two kinds of job run in the background.
Jobs you can trigger
Listed under Settings, then Jobs, with what each does, when it last ran, when it runs next, and a run-now button. Only jobs relevant to your setup are shown.
| Job | What it does | Runs |
|---|---|---|
| External Library Sync | Imports tracks from connected external libraries. | Every 30 minutes by default |
| Discovery Sweep | Evaluates discovery feeds and triggers integrations. | On a fixed interval |
| Media Server Sync | Keeps media server playlists named right and topped up. | Hourly |
| Wanted Sweep | Retries watched failed tracks on a release-age cadence. | On a fixed interval, off by default |
Running the discovery sweep by hand forces it past its own due checks, so a manual run does what you expect rather than quietly doing nothing because a feed is not yet due. The other jobs do a normal pass, which still honours their own per-item cadence. Neither permanently shifts the schedule.
Maintenance jobs
These run on a fixed schedule and are not user-triggerable.
| Job | What it does |
|---|---|
| Cache warmup | Keeps commonly needed catalog data warm. |
| Search cleanup | Clears finished searches out of slskd. |
| Version check | Checks the container registry for a newer release. |
| Session cleanup | Removes expired sessions. |
| Recording ID enrichment | Resolves MusicBrainz recording identifiers for tracks with an ISRC. |
| Cache cleanup | Reaps expired metadata cache entries. |
| Recycle bin cleanup | Permanently removes replaced library files once their retention window passes. |
| Drop import cleanup | Clears finished drag-and-drop import batches and their staged files. |
| Held import cleanup | Discards review-queue files once their retention window passes. |
Logs
Settings, then Logs, administrators only.
- Live viewer with auto-refresh.
- Filter by level.
- Export to a file.
- Change the log level from the interface. It applies immediately, with no restart.
Logs are written to /data/logs, so they survive a container recreate and can be read from the host.
The credentials you enter in Settings are kept out of the logs, and a test asserts it on the paths that handle them.
Health
Two endpoints, both unauthenticated and safe to point a monitor at.
| Endpoint | What it returns |
|---|---|
GET /api/health | Liveness, plus runtime details including the architecture the image is running on. |
GET /api/status | Process detail: platform, Node version, memory use, and uptime. |
The compose health check uses the first one against the internal API port.
Inside the application, each integration shows a live status on its settings card, so you can tell a bad credential from a service that is simply down.
Startup
Boot aborts for genuine prerequisites: the database and its migration, a required folder that is not usable, the core music catalog, and the one-shot 1.x migration seed. Every integration logs a warning and continues.
When a required folder fails, the container log names the offending path and the ownership fix before the API stops with Required service(s) failed: Paths.
A music library that is readable but not writable does not stop the boot. Synthseek starts and says so, in the log and on the Paths entry of the health view. Browsing works, and imports into the library fail until it is writable.
Updates
Synthseek checks the public container registry for newer releases and shows a banner when one is available. The patch notes for it are in Settings, then Updates, as a timeline you can read without leaving the application.
To update, pull the new image and recreate the container:
docker compose pull
docker compose up -dWhat happens on an upgrade
Where there is room, the container proves the migration on a copy before touching your live database.
- Pending schema changes are detected.
- A snapshot of your database is written to
/data/backups. - If there is room and the database sits in its default location, the migration is applied to a copy, not to your database.
- The migrated copy is validated.
- Only if validation passes is the copy swapped into place.
- If anything fails during a copy-validated upgrade, your live database is untouched, the snapshot is kept, and the failed copy is kept for inspection.
The last ten snapshots are retained. Every migration run is logged to /data/logs/migrate.log.
If there is not enough free space for a copy, or your database lives outside its default location, Synthseek falls back to migrating in place and tells you, having already taken the snapshot.
Backups
Everything Synthseek knows lives under /data. Back up that volume and you can restore the instance completely.
Your music files live under /music and are not Synthseek’s to back up. The one case where it removes a file from there is a quality upgrade, which moves the replaced copy to the recycle bin under /data before the retention sweep clears it.
Take your own backup before a major version upgrade. The automatic snapshot covers schema migration failure; it is not a substitute for a backup you control.
Architecture support
Images are published for both amd64 and arm64. Each architecture is built on a native runner with its own native dependencies, and each is smoke tested before publication by starting it and confirming the running architecture through the health endpoint. A published manifest is not taken as proof that a non-host architecture works.