Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TheOutdoorProgrammer/crate/llms.txt

Use this file to discover all available pages before exploring further.

The fastest way to run Crate is with Docker Compose. The stack below launches Crate and slskd together, wires up a shared downloads volume so Crate can see files the moment slskd finishes fetching them, and mounts a shared library folder so both services stay in sync. All you need is a Soulseek account and Docker installed on your machine.

​
Prerequisites

  • Docker and Docker Compose (v2) installed
  • A Soulseek account — register free at slsknet.org
  • Ports 6969 (Crate) and 5030 (slskd) available on your host

​
Setup

1

Create your docker-compose.yml

Create a new directory for your Crate installation and save the following as docker-compose.yml inside it. This is the canonical deployment configuration from the Crate project.
docker-compose.yml
services:
  crate:
    image: ghcr.io/theoutdoorprogrammer/crate:latest
    ports:
      - "6969:6969"
    volumes:
      - ./crate:/app/data             # SQLite databases
      - ./slskd/downloads:/app/downloads  # Must match slskd's download dir
      - ./library:/app/library       # Organized music library
    environment:
      - CRATE_SLSKD_URL=http://slskd:5030
      - CRATE_SLSKD_API_KEY=your_api_key
    depends_on:
      - slskd
    restart: unless-stopped

  slskd:
    image: slskd/slskd:latest
    ports:
      - "5030:5030"
    volumes:
      - ./slskd:/app                  # slskd data (config, downloads)
      - ./library:/music             # Share your library on Soulseek
    environment:
      - SLSKD_REMOTE_CONFIGURATION=true
      - SLSKD_API_KEY=your_api_key
      - SLSKD_SOULSEEK_USERNAME=your_soulseek_username
      - SLSKD_SOULSEEK_PASSWORD=your_soulseek_password
    restart: unless-stopped
2

Replace the placeholder values

Open docker-compose.yml and substitute the three placeholder values before starting anything:
PlaceholderReplace with
your_api_keyAny string you choose — must be identical in both CRATE_SLSKD_API_KEY and SLSKD_API_KEY
your_soulseek_usernameYour Soulseek account username
your_soulseek_passwordYour Soulseek account password
Alternatively, create a .env file in the same directory and reference the variables there:
.env
SLSKD_SOULSEEK_USERNAME=your_soulseek_username
SLSKD_SOULSEEK_PASSWORD=your_soulseek_password
CRATE_SLSKD_API_KEY=your_api_key
CRATE_LIBRARY_PATH=./library
3

Start the stack

From the directory containing your docker-compose.yml, run:
docker compose up -d
Docker will pull both images and start the containers. The first startup may take a minute while slskd connects to the Soulseek network. You can follow progress with:
docker compose logs -f
4

Open the Crate UI

Navigate to http://localhost:6969 in your browser. You should see the Crate library view. If slskd is still connecting, wait 30–60 seconds and refresh — Crate will show a warning if it cannot reach slskd.
On mobile, add the page to your home screen for a full-screen app-like experience. Crate’s UI is designed mobile-first with a bottom navigation bar.
5

Search for an artist and click Watch

Use the Search tab to find an artist by name. Crate queries the active metadata provider (MusicBrainz by default) and returns matching artists. Tap an artist to preview their discography, then click Watch to add them to your library.When you watch an artist, Crate immediately sets all their album tracks to wanted status and queues them for download.
6

Crate downloads automatically

Head to the Downloads tab to watch the queue in real time. For each wanted track, Crate:
  1. Searches slskd for matching files on the Soulseek network
  2. Scores every result by quality tier, artist-name match, and peer availability
  3. Downloads the highest-scoring file via slskd
  4. Moves the completed file into ./library using the naming template {artist}/{album} ({year})/{track:2} - {title}
  5. Writes embedded metadata tags (ID3v2 for MP3, Vorbis comments for FLAC, RIFF INFO for WAV)
  6. Marks the track owned
Failed downloads retry automatically with backoff (5 min → 15 min → 30 min → 1 h).

​
Volume Layout

After running the stack, your working directory will look like this: 
my-crate/
├── docker-compose.yml
├── .env
├── crate/               # Crate's SQLite databases (crate.db, cache.db, activity.db)
├── slskd/
│   └── downloads/       # slskd writes completed downloads here
│                        # Crate reads from this same path via /app/downloads
└── library/             # Organized, tagged music — mounted in both containers
The downloads volume must be shared between Crate and slskd. In the configuration above, ./slskd/downloads on the host is mounted as /app/downloads in Crate and as part of /app in slskd. If these paths point to different host directories, Crate will not find files after slskd downloads them and every download will appear to stall or fail. Double-check your volume mounts if downloads complete in slskd but never reach organizing status in Crate.

​
What’s Next

Now that Crate is running, explore the full set of environment variables and in-UI settings to tailor it to your setup.

Configuration

All environment variables with defaults, provider format, and a guide to the Settings UI.

Introduction

Deeper look at Crate’s architecture, status model, and technology stack.

Build docs developers (and LLMs) love

Get started for freeTalk to us