Getting Started · Synthseek Docs

Before you begin

You need three things.

Docker and Docker Compose, on a machine that stays on.
A running slskd instance, with its web API reachable from the Synthseek container. slskd is what actually performs peer-to-peer downloads; Synthseek drives it and never speaks the Soulseek protocol itself. Full setup is on the Download Sources page.
Two folders: one where slskd puts completed downloads, and one where your organised music library lives. Synthseek reads from the first and writes to the second.

An AcoustID key is optional but strongly recommended. Without one, Synthseek cannot verify by listening that a downloaded file is what you asked for. It is free and takes a minute to obtain.

Installing with Docker Compose

Create a docker-compose.yml:

yaml

services:
  synthseek:
    image: ghcr.io/arukaraz/synthseek:latest
    container_name: synthseek
    restart: unless-stopped
    ports:
      - "4400:4400"
    volumes:
      - /path/to/synthseek/data:/data
      - /path/to/your/music:/music
      - /path/to/slskd/downloads/complete:/downloads
    environment:
      - PUID=1000
      - PGID=1000
      - AUTH_SECRET=replace-with-a-long-random-string
    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://localhost:4401/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Generate the auth secret with:

bash

openssl rand -base64 48

Then start it:

bash

docker compose up -d

Open http://your-server:4400.

Your slskd address and API key are not set here. The setup wizard collects them on first run and stores them in the database, along with everything else you connect.

What each volume is for

Container path	What goes there	Notes
`/data`	The database, configuration, logs, artwork cache, backups, drop-import staging, files held for review, and the recycle bin.	Back this up. Everything Synthseek knows lives here.
`/music`	Your organised music library. Beets writes here.	Can be mounted read-only, in which case Synthseek boots and browsing works, but imports into the library fail until it is writable.
`/downloads`	The folder slskd writes completed downloads to.	Must be writable. This is the same folder slskd calls its “complete” directory.

Ports

Port	What it is
`4400`	The web interface. Change with `WEB_UI_PORT`.
`4401`	The internal API. Fixed inside the container, used by the health check. Not something you normally publish.

PUID and PGID

Synthseek runs as an unprivileged user inside the container. It takes ownership of its own /data volume at boot and never touches the ownership of your music and downloads folders. Set PUID and PGID to the user and group that own your downloads and music folders on the host.

If a required folder is not usable, Synthseek stops at boot rather than starting broken. The container log names the offending path and the ownership fix, and the API then stops with Required service(s) failed: Paths. A music library that is readable but not writable does not stop the boot: Synthseek starts and browsing works, and imports into the library fail until you fix the ownership.

First run

The first time you open Synthseek, a setup wizard walks you through five steps.

Administrator account. Create the first account. This account is the instance owner and cannot be demoted or deleted.
slskd. Enter the URL and API key of your slskd instance. Synthseek tests the connection and tells you what it found. You can continue past a failed test, and Synthseek will boot anyway and show the integration as unhealthy so you can fix it from Settings.
Plex. Optional. A popup opens for you to sign in at plex.tv, then you pick which of your servers Synthseek should target. This is what enables library rescans and playlist sync.
Enrichment services. Optional. An AcoustID key, a Last.fm key, a fanart.tv key, a Songlink key, and a MusicBrainz contact email. All are free, and each one improves a different thing: verification accuracy, discovery, artist images, link imports, and rate limits. Discogs is added later, from Settings.
Done. You land in the application.

Every value the wizard collects lives in the database and can be changed later from Settings. Nothing is written to a configuration file you would have to edit by hand.

Your first request

Go to Search and type an artist, a song, an album, or a mood.
Pick a result. A request window opens.
Optionally set the format, the bitrate, and how strictly each should be matched. The defaults are fine.
Confirm.

The request appears on the Requests screen straight away. You will see each track move through searching, downloading, and importing, live. When it finishes, the tracks appear in your Library.

If you requested a playlist, the request is accepted immediately and the tracks fill in behind it. A progress dock in the corner keeps you posted while that happens.

Where to go next

Configuration to tune the engine, or to understand what a setting actually does before changing it.
Users and Permissions to add the rest of your household.
Integrations to connect Plex, Lidarr, or your listening history.
AI Assistants to let Claude or another assistant drive your library in plain language.