A web-based client for the Soulseek file-sharing network, with release lookups, a settings editor and other quality-of-life features inspired by Nicotine+. It is based on slskd and works with an existing slskd configuration and data.
Note
This is a modified version of slskd. It is not maintained by, endorsed by, or affiliated with the slskd project or its author(s).
Please report problems with webseekd here, not to the slskd project.
A new Releases page finds an album on MusicBrainz first, then looks for it on Soulseek.
- Search by
Artist - Album, plain text, a MusicBrainz release, release-group or artist link, or a bare release ID. - See each release's track list, format, label and catalog number, with cover art from the Cover Art Archive. Covers the archive doesn't have are looked up on Deezer and iTunes.
- Search Soulseek for a release in one click. Matching folders are ranked by how many of the release's tracks they hold (by track number, title and length) and by file quality. Download the matched tracks, with or without the folder's other files (cover art, logs), into an
Artist - Album (Year)folder. - Releases you search for are saved and linked to their Soulseek searches, so you can come back to them later.
The new integrations.musicbrainz options are all optional:
integrations:
musicbrainz:
disabled: false
url: https://musicbrainz.org # point at a mirror to avoid the public rate limit
request_interval: 1000 # milliseconds between requests; musicbrainz.org allows one per second
cover_fallback: true # look up missing covers on Deezer and iTunesA Settings page edits slskd.yml through forms, organized like Nicotine+'s preferences (Profile, Network, Shares, Downloads, Uploads, Users & Bans, Searches & Rooms, Web & Security, Cleanup, Integrations). It includes:
- An editor for user groups and ban lists.
- A profile editor for the description and picture other users see, with a preview. Uploaded pictures are stored in
<app dir>/profile/.
Changes are validated by the server and saved together. Only the keys you changed are written; comments, ordering and keys the page doesn't know about are left as they were.
The page needs remote_configuration: true in slskd.yml, the same as slskd's built-in YAML editor.
-
Every user has a profile page at
/users/<username>, showing their status, statistics, group, description, picture and shared files. You can ban or unban them there, or gift them days of privileges. -
Clicking a username anywhere (search results, transfers, chat, rooms) opens that user in a side panel without leaving the page.
-
Right-clicking a username opens a menu: View Profile, Browse Files, Send Message…, Open in Users Tab and Copy Username.
-
Profiles show a flag for the country the user's IP address is in. Countries come from DB-IP's free IP to Country Lite database (CC BY 4.0), which is downloaded to
data/geoip/on first use and again each month. Lookups never leave your machine. To turn this off:integrations: geoip: disabled: true
-
The Interests tab's people lists (People who like … and People like you) show each user's picture and description. They load a few at a time as the cards scroll into view, because each one needs a connection to that user.
- A filter form next to the filter text box, with minimum and maximum size and length, minimum upload speed, maximum queue length, minimum files per folder, required and excluded words, and formats. Filters can be saved and reused.
- A Clear all button that deletes every finished search.
- On Windows, paths derived from
--app-dirare normalized, so values with forward slashes (e.g.C:/slskd) no longer break downloads. - Validating options no longer fails when two requests read the config file at the same time.
- Error messages survive reverse proxies. Cloudflare replaces a 502 from the server with its own error page, so MusicBrainz failures are now reported as 503, with the reason shown in the UI and logged.
- There is no published Docker image. Every push to
mainpublishes Linux builds (linux-x64andlinux-arm64) to the rollingqol-latestrelease. bin/update-vpsinstalls the latest build over an existing systemd install and rolls back if it doesn't start.- Builds are versioned after the slskd release they're based on, e.g.
0.26.0.65534+abc1234.
-
Create a user and download the latest build. Use
webseekd-linux-arm64.tar.gzon ARM machines:sudo useradd --system --create-home --home-dir /var/lib/webseekd webseekd sudo mkdir -p /opt/webseekd curl -fL https://github.com/xctwt/webseekd/releases/download/qol-latest/webseekd-linux-x64.tar.gz \ | sudo tar -xz -C /opt/webseekd sudo chown -R webseekd:webseekd /opt/webseekd -
Create
/etc/systemd/system/webseekd.service:[Unit] Description=webseekd After=network-online.target Wants=network-online.target [Service] Type=simple User=webseekd Group=webseekd ExecStart=/opt/webseekd/webseekd --app-dir /var/lib/webseekd Restart=on-failure [Install] WantedBy=multi-user.target
-
Start it:
sudo systemctl daemon-reload sudo systemctl enable --now webseekdOn the first run webseekd creates
/var/lib/webseekd/slskd.yml. The configuration file keeps slskd's name, so existing slskd configurations work unchanged. Edit it to add your Soulseek username and password, change the web UI login (the default isslskd/slskd), and setremote_configuration: trueif you want to use the Settings page. Then runsudo systemctl restart webseekd.config/slskd.example.ymllists every option. -
Open
http://<server>:5030. If you put it behind a reverse proxy or Cloudflare, see the reverse proxy guide, and make sure WebSockets are allowed. Search results and transfers update over a WebSocket connection.
Build the image from this repository:
git clone https://github.com/xctwt/webseekd.git
cd slskd
docker build -t webseekd .Then run it with Docker Compose:
services:
webseekd:
image: webseekd
container_name: webseekd
user: "1000:1000" # or remove this line and set the PUID and PGID environment variables instead
ports:
- "5030:5030" # HTTP
- "5031:5031" # HTTPS, with a self-signed certificate
- "50300:50300" # incoming Soulseek connections
environment:
- SLSKD_REMOTE_CONFIGURATION=true
volumes:
- <path/to/application/data>:/app
restart: alwaysSLSKD_REMOTE_CONFIGURATION lets you change settings from the web UI, including the Settings page. You might not want it on an internet-facing install. See the Docker guide for more.
Building needs the .NET 10 SDK, Node.js 22 and bash:
git clone https://github.com/xctwt/webseekd.git
cd slskd
./bin/build # builds and tests the web UI and the server
./bin/publish --runtime linux-x64 # self-contained build in dist/linux-x64, run with ./webseekd-
systemd: run the update script on the server:
curl -fsSL https://raw.githubusercontent.com/xctwt/webseekd/main/bin/update-vps | sudo bashThe script finds the install folder from the
webseekdservice, or theslskdservice if there is nowebseekdone. SetSERVICE=<name>orINSTALL_DIR=<folder>if yours is different. It stops the service, keeps the current version in<install folder>.previous, installs the new build, and puts the previous version back if the new one doesn't stay up. Your config and data are not touched. -
Docker: run
git pull, rebuild the image, and recreate the container.
webseekd uses the same application directory as slskd: the same slskd.yml, the same SLSKD_* environment variables, the same database in data/, and the same logs. Nothing needs converting. Only the program is renamed: the binary is webseekd instead of slskd.
- Back up your application directory. This is the folder with
slskd.ymlin it: the path given to--app-dir,~/.local/share/slskdby default, or the/appvolume in Docker. For example,sudo tar -czf ~/slskd-backup.tar.gz -C /var/lib slskd. - Install webseekd over slskd:
- slskd binaries under systemd: run the update script from Updating. It detects the install folder from your service and replaces only the binaries and web UI. Your service keeps starting
slskd, which becomes a link towebseekd; you can changeExecStarttowebseekdafterwards. - slskd Docker image: build the
webseekdimage as described under Docker. Stop the old container, then start a new one with the same volumes, ports and environment variables, but withimage: webseekd. - slskd binaries started by hand: stop slskd, extract the webseekd build over the old folder (delete the old
wwwrootfolder first), and startwebseekdwith the same--app-dir.
- slskd binaries under systemd: run the update script from Updating. It detects the install folder from your service and replaces only the binaries and web UI. Your service keeps starting
- Optional: set
remote_configuration: trueto use the Settings page, and add anintegrations.musicbrainzorintegrations.geoipsection if the defaults don't suit you. - Open the web UI and hard-refresh (Ctrl+F5). Your browser may still have the old UI cached.
- Remove the
integrations.musicbrainzandintegrations.geoipsections fromslskd.yml, if you added them. slskd ignores them at startup, but its built-in config editor refuses to save a file containing keys it doesn't recognize. - Reinstall slskd: extract an slskd release over the install folder (delete
wwwrootand thewebseekdbinary first), or switch the container back to the slskd image. Ifslskdin the install folder is a link towebseekd, delete it too. data/releases.json(saved releases) is only used by webseekd, so you can delete it, along withdata/geoip/. Uploaded profile pictures inprofile/keep working ifsoulseek.picturepoints at one.
webseekd runs as a daemon or Docker container in your network (or in the cloud) and is used from a web browser. It's designed to be exposed to the internet, and everything is secured with a token that you can control. It also supports reverse proxies, so it works well with other self-hosted tools.
Search the same way you would in the official Soulseek client, and enter several searches in quick succession.
Sort and filter search results with the filters you already know. Dismiss the results you're not interested in, and download the ones you want in a couple of clicks.
Monitor the speed and status of downloads, grouped by user and folder. Click the progress bar to fetch your place in the queue, and use the selection tools to cancel, retry or clear completed downloads. Use the controls at the top to manage downloads by status.
webseekd can do almost everything the official Soulseek client can: browse user shares, join chat rooms and chat privately with other users.
Log in to the web UI with the default username slskd and password slskd to finish configuring it. Change these if the web UI will be reachable from the internet.
Every option is described in the configuration guide, and config/slskd.example.yml is an example configuration file.
The application directory is ~/.local/share/slskd on Linux and macOS and %localappdata%/slskd on Windows, unless you set --app-dir. slskd.yml is created there the first time the application runs.
webseekd may need extra configuration behind a reverse proxy. See the reverse proxy guide.
webseekd is licensed under the GNU Affero General Public License v3.0 (AGPLv3) with Additional Terms pursuant to Section 7 of the AGPLv3. See LICENSE for the full text of both, and NOTICE.