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.

Crate has two configuration layers. The first is a set of environment variables read at startup that control infrastructure concerns — which port to listen on, where to store databases, and how to reach slskd. The second is a live Settings UI accessible from the browser that lets you change provider preferences, quality tiers, naming templates, integrations, and more without restarting the container. Most day-to-day tuning happens in the UI; the env vars only need to be set once when you deploy.

​
Environment Variables

Set these in your docker-compose.yml environment block, in a .env file, or in the shell before running Crate. Variables without a default are required.
​
CRATE_PORT
string
default:"6969"
The HTTP port Crate listens on. Change this if port 6969 conflicts with another service on your host. Remember to update the ports mapping in your Compose file to match.
​
CRATE_DB_PATH
string
default:"./crate.db"
Path to the main SQLite database that stores artists, albums, tracks, and the download queue. In the Docker image this defaults to /app/data/crate.db via the Dockerfile ENV instruction — mount a volume at /app/data to persist it across container restarts.
​
CRATE_CACHE_PATH
string
default:"./cache.db"
Path to the provider cache database. Crate caches metadata responses from MusicBrainz and Deezer here to avoid redundant API calls. In the Docker image defaults to /app/data/cache.db.
​
CRATE_ACTIVITY_PATH
string
default:"./activity.db"
Path to the activity log database, which records every download event (search, download, complete, fail). Stored separately from the main database so it can be rotated independently. In the Docker image defaults to /app/data/activity.db.
​
CRATE_SLSKD_URL
string
default:"http://localhost:5030"
Base URL of the slskd API. When running both services in the same Compose stack, use the Docker service name as the hostname — for example http://slskd:5030 — so container networking resolves correctly.
​
CRATE_SLSKD_API_KEY
string
Required. The API key Crate uses to authenticate with slskd. This value must exactly match SLSKD_API_KEY set on the slskd container. Any non-empty string is valid; treat it like a password.
​
CRATE_DOWNLOADS_DIR
string
default:"./downloads"
The local filesystem path where slskd writes completed downloads, as seen from inside the Crate container. This must resolve to the same host directory that slskd uses for its download output. In the Docker image defaults to /app/downloads.
​
CRATE_LIBRARY_PATH
string
default:"./library"
The path where Crate moves and organizes finished files. In the Docker image defaults to /app/library. This directory should be mounted as a volume so files survive container rebuilds, and ideally shared with Navidrome or your media server.
​
CRATE_SCAN_INTERVAL
string
default:"6h"
How often Crate’s background scheduler runs. Each cycle re-queues all wanted tracks, checks watched artists for new releases, and runs the quality-upgrade scanner. Accepts Go duration syntax: 30m, 2h, 24h, etc.
​
CRATE_PROVIDERS
string
A comma-separated list of provider definitions in the format name:binary:port. Each entry tells Crate the name to display in the UI, the path to the provider binary, and the local gRPC port it should listen on. The two bundled providers (provider-musicbrainz and provider-deezer) are included in the Docker image and configured by default.
​
CRATE_MB_USER_AGENT
string
The User-Agent header sent with all MusicBrainz API requests. MusicBrainz requires a descriptive user-agent that identifies your application and provides a contact URL. Override this if you are running a fork or need to identify your specific deployment.

​
Provider string format

Each provider entry follows the pattern name:binary:port:
FieldDescription
nameDisplay name used in the UI and stored against library entities
binaryPath to the gRPC provider binary, relative to the Crate working directory
portLocal port the provider binary will bind to for gRPC communication
# Default — both bundled providers
CRATE_PROVIDERS=musicbrainz:./provider-musicbrainz:50051,deezer:./provider-deezer:50052

# MusicBrainz only
CRATE_PROVIDERS=musicbrainz:./provider-musicbrainz:50051

# Custom provider on a non-default port
CRATE_PROVIDERS=musicbrainz:./provider-musicbrainz:50051,myprovider:/opt/my-provider:50053

​
Minimal .env example

.env
# Required
CRATE_SLSKD_API_KEY=change_me_to_a_strong_secret

# Optional — override defaults as needed
CRATE_SLSKD_URL=http://slskd:5030
CRATE_LIBRARY_PATH=./library
CRATE_SCAN_INTERVAL=6h
CRATE_PORT=6969

​
Settings UI

Everything in the table above is infrastructure configuration. Once Crate is running, open Settings in the sidebar (or bottom nav on mobile) to configure the following without restarting:

​
Authentication

Crate does not include built-in authentication. Anyone who can reach the configured port can read and modify your library. If you expose Crate beyond your local network, place a reverse proxy with authentication in front of it. Recommended options include Cloudflare Zero Trust (free tier available), Authelia, or nginx with auth_basic. The Lidarr API shim at /api/v1/ accepts any value in the X-Api-Key header or apikey query parameter — it does not validate the key against any secret.

Build docs developers (and LLMs) love

Get started for freeTalk to us