Beltr on your home server

Quick start

docker run -d --name beltr -p 8477:8477 -p 8478:8478 \
  -e PUID=1000 -e PGID=1000 -e TZ=UTC \
  --restart unless-stopped \
  -v /path/to/appdata/beltr:/config \
  -v /path/to/bulk/beltr-library:/library \
  -v /path/to/beltr-cache:/cache \
  -v /path/to/your/music:/media:ro \
  ghcr.io/casavargas/beltr:latest

Set PUID and PGID to the user that owns your media folder; on Unraid that’s 99 and 100.

Or with Compose (the compose file and .env.example are on GitHub):

cp .env.example .env
docker compose --profile cpu up -d

Then open http://<server>:8477/dashboard to add music, and put /tv on the screen you sing at. Phones scan the QR code on the TV. For a microphone, open https://<server>:8478 instead on the laptop or phone that has it, and accept the one-time certificate warning: browsers only allow the mic on a secure page.

Pick an image

Version tags pin a release (for example 1.62.0, or 1.62 for the newest patch of that line); latest follows releases.

Unraid

Install from Community Applications: open the Apps tab and search for Beltr. There are CPU, NVIDIA and Intel GPU templates; install one. Find Beltr in Community Applications, or read the full Unraid install guide.

TrueNAS

A Beltr package for the TrueNAS community train has been requested and isn’t in the catalog yet (the app request). Until it’s accepted, run Beltr on TrueNAS SCALE as a custom app with the compose file above; it uses the same volumes and port. This page will say so when the catalog listing is live.

Apple Silicon Macs

It works, and it’s the slow way to run Beltr on a Mac. Pull latest under Docker Desktop or OrbStack and you get the arm64 image automatically. Inside the Linux VM there’s no CoreML and no GPU, so vocal separation runs on the CPU: on an M4 Mac mini a 3:11 song took 121 seconds, against about 11 seconds in the native Mac app. That’s fine for a party server that prepares songs in the background. If you want the fastest Beltr on that Mac, download the Mac app instead.

Keep /library on a named volume or a VirtioFS bind mount; there’s no --device or --gpus to pass.

Use another computer’s GPU

The container separates on its CPU. If there’s a Mac, or a Windows PC with Beltr’s GPU pack, on the same network, that machine can do the separation instead, and the container falls back to itself when it’s off.

• On the fast machine: Beltr, then Settings, Processing, and Share this computer’s separation. Turn it on and copy the address and token.
• On the container: Settings, Processing, Separation helper. Paste both, press Test, then turn it on.

Songs prepare at the fast machine’s speed while the library, the queue and every screen stay on the server.

Trusted network only, the same rule as the host PIN: anyone holding the token can send audio to the sharing machine. Don’t expose a sharing install to the internet without a real authentication layer in front of it.

Volumes, ports and the license

Port 8477, plus 8478 for the self-signed HTTPS that microphones need. Put your key in BELTR_LICENSE_KEY or drop it at /config/license.key; it activates once against this install and then works offline. Leave it blank for the 5-song trial.

Buy Beltr, $19.99