slskd · Whatbox

Wiki > slskd

slskd is a modern client-server application for the Soulseek file-sharing network, controlled through a web interface.

23578 was randomly generated for this article for the web interface, and 11789 for incoming Soulseek connections. You may use any other 5-digit ports between 10000 and 32767.

You will need a Soulseek account. If you don't have one, slskd will create it the first time it connects with a username and password that aren't taken.

Installation

Connect to your slot via SSH.

Download and extract the latest Linux release:

 mkdir -p ~/slskd ~/.config/slskd
 wget $(curl -s https://api.github.com/repos/slskd/slskd/releases/latest | grep browser_download_url | grep linux-x64.zip | cut -d\" -f4)
 unzip -o slskd-*-linux-x64.zip -d ~/slskd/
 chmod +x ~/slskd/slskd
 rm slskd-*-linux-x64.zip

Create the folders for downloads and incomplete files:

 mkdir -p ~/files/slskd/downloads ~/.config/slskd/incomplete

Create the configuration file:
```
 nano ~/.config/slskd/slskd.yml
```

Paste in the following. Replace the two Soulseek credentials and replace changeme with a unique web interface password (do not reuse your Whatbox password). Optionally, change or add shared folders under shares:

 web:
   port: 23578
   ip_address: 0.0.0.0
   https:
     disabled: true
   authentication:
     username: user
     password: changeme
 soulseek:
   username: your_soulseek_username
   password: your_soulseek_password
   listen_ip_address: 0.0.0.0
   listen_port: 11789
 directories:
   downloads: /home/user/files/slskd/downloads
   incomplete: /home/user/.config/slskd/incomplete
 shares:
   directories:
     - /home/user/files/slskd/downloads

Save with Ctrl + S and exit with Ctrl + X.

The shared folder must exist and paths must be absolute. Leave shares out entirely if you don't want to share anything, though many Soulseek users will refuse uploads to people who share nothing.

Start slskd in a screen session:

 screen -dmS slskd /home/user/slskd/slskd --app-dir /home/user/.config/slskd

Visit http://server.whatbox.ca:23578 and log in with the web username and password you set in step 5.

The first start can take a minute while slskd scans your shares. You can watch the output with screen -r slskd, and detach again with Ctrl + A, then D.

Configuration

All settings live in ~/.config/slskd/slskd.yml. slskd watches this file and applies most changes without a restart. The official configuration reference lists every option.

Some settings worth knowing:

Upload limits — uploads count toward your slot's traffic. Use transfers.upload.slots and transfers.upload.speed_limit (in KiB/s) to cap them.
Remote configuration — remote_configuration: true lets you edit the YAML from the web interface. Leave it off unless you need it.
Rescanning shares — after adding shared files, trigger a share rescan from the Shares page in the web interface.

Automatically Restart (optional)

Create a restart script:

 touch ~/slskd_restart.cron
 nano -w ~/slskd_restart.cron

Paste in the following:

 #!/bin/bash
 if pgrep -fx "/home/user/slskd/slskd --app-dir /home/user/.config/slskd" > /dev/null
 then
     echo "slskd is running."
 else
     echo "slskd is not running, starting slskd"
     screen -dmS slskd /home/user/slskd/slskd --app-dir /home/user/.config/slskd
 fi
 exit

Save and exit.

Make the script executable:
```
 chmod +x ~/slskd_restart.cron
```
Open your crontab:
```
 EDITOR=nano crontab -e
```

Add these lines, then save and exit:

 @reboot /home/user/slskd_restart.cron >/dev/null 2>&1
 */5 * * * * /home/user/slskd_restart.cron >/dev/null 2>&1

HTTPS via Managed Links (optional)

On the Manage Links page, click Add a custom app.
Name it slskd, enter port 23578, and open Advanced options to enable WebSockets — slskd's interface needs them.
Once the link works, change ip_address: 0.0.0.0 under web: to ip_address: 127.0.0.1 in ~/.config/slskd/slskd.yml so the plain HTTP port is no longer public, then restart slskd:
```
 pkill -f slskd/slskd; screen -dmS slskd /home/user/slskd/slskd --app-dir /home/user/.config/slskd
```

Leave soulseek.listen_ip_address at 0.0.0.0. Other Soulseek users must be able to reach port 11789 directly.

Updating

If you set up the restart script, comment out its two lines in your crontab (EDITOR=nano crontab -e) so it doesn't restart slskd mid-update.
Stop slskd:
```
 pkill -f slskd/slskd
```
Repeat step 2 of Installation. Your configuration and database in ~/.config/slskd are kept.
Start slskd again with the command from step 6, and uncomment the crontab lines.

Uninstalling

Remove the two slskd_restart.cron lines from your crontab (EDITOR=nano crontab -e).

Stop slskd and delete its files:

 pkill -f slskd/slskd
 rm -r ~/slskd ~/.config/slskd ~/slskd_restart.cron

Partially downloaded files in ~/.config/slskd/incomplete are removed along with it. Your finished downloads in ~/files/slskd are left in place; delete them separately if you no longer need them.

Troubleshooting

slskd exits immediately complaining about an address or port — another program is using one of your ports. Pick a different port for web.port or soulseek.listen_port and restart slskd.
Can't log in to the web interface — enter the web credentials from web.authentication, not your Soulseek or Whatbox credentials.
YAML errors on start — the file is indentation-sensitive. Use spaces, not tabs, and keep the nesting exactly as shown above.
Soulseek shows you as unable to receive connections — check that soulseek.listen_ip_address is 0.0.0.0 and the port is in the 10000–32767 range.