Documentation

DroppedNeedle does not download from Soulseek itself. It orchestrates a user-provided slskd instance over slskd’s local HTTP API: it asks slskd to search, tells it what to download, and imports the finished files. You supply, run, and are responsible for slskd and its shared folders. DroppedNeedle has no Soulseek protocol code, only an HTTP client for slskd. It never joins or distributes on the Soulseek/P2P network.

Requirements

  • slskd 0.25.0 or newer. Version 0.25.1 is the version DroppedNeedle is verified against. Pin it: slskd/slskd:0.25.1.
  • A Soulseek account configured in slskd.
  • At least one shared folder configured in slskd (slskd.yml -> shares.directories). Soulseek bans leechers. This is a slskd and Soulseek network requirement, not a DroppedNeedle one, but without it you will be disconnected and searches will return nothing.
  • slskd’s HTTP API reachable from the DroppedNeedle container.
  • An API key in slskd (slskd.yml -> web.authentication.api_keys).

The downloads bind-mount

This is the most common misconfiguration. Read it carefully before starting.

When slskd finishes a download, it writes the file into its own downloads directory (slskd.yml -> directories.downloads), preserving the remote folder structure. DroppedNeedle imports a finished download by moving that file out of slskd’s downloads directory into your music library with an atomic os.rename. No copy, no leftover, no doubled storage.

For that move to work, two things must be true:

  1. DroppedNeedle must be able to see slskd’s downloads directory (bind-mounted read-write into the DroppedNeedle container).
  2. That directory must be on the same filesystem as your music library. A rename across filesystems fails with EXDEV. If the two paths are on different filesystems, downloads complete in slskd but nothing ever lands in your library.

DroppedNeedle validates this at startup, checking that the path is set, exists, is writable, and is on the same filesystem as the library, and marks the download client DEGRADED with a clear reason if anything fails. It still boots to the UI so you can diagnose and fix it.

In docker-compose.yml:

environment:
  - SLSKD_DOWNLOADS_PATH=/slskd-downloads
volumes:
  - /path/to/your/music:/music:rw                # library
  - /path/to/slskd/downloads:/slskd-downloads:rw # MUST be the same filesystem as /music

The host path /path/to/slskd/downloads must be on the same underlying filesystem as /path/to/your/music. If your music lives on one mount point and slskd’s downloads live on another, the atomic rename will fail.

API key

Configure an API key in slskd.yml and provide it to DroppedNeedle under Settings > Download Client (URL plus API key). DroppedNeedle sends it as the X-API-Key header on every request. It is stored encrypted and never written to logs.

Example slskd.yml

The essential sections:

soulseek:
  username: your-soulseek-username
  password: your-soulseek-password

shares:
  directories:
    - /data/share   # at least one folder of files you share (required by the network)

directories:
  downloads: /data/downloads   # the host path you also bind-mount into DroppedNeedle

web:
  authentication:
    api_keys:
      droppedneedle:
        key: choose-a-long-random-key   # give this to DroppedNeedle's Download Client settings

Making slskd reachable from DroppedNeedle

If both containers run on the same Docker host, put them on the same Docker network and address slskd by its container name:

# In your DroppedNeedle compose file, Settings > Download Client:
# URL: http://slskd:5030

If slskd runs on a different host or is exposed on the Docker host’s network, use its reachable IP or hostname and the port slskd listens on (default 5030).

DroppedNeedle never needs to be reachable from slskd; communication is one-directional.

Verifying the setup

After starting DroppedNeedle and configuring the download client in Settings > Download Client:

  1. Click Test. A successful test confirms the URL and API key are correct and slskd is reachable.
  2. Check the downloads-mount health shown on the same page. It should read: set, exists, writable, same filesystem. Fix any warnings before making requests.
  3. If the client shows DEGRADED, check the reported reason. Common causes are listed in the FAQ.