Documentation · Install · Join a server · Configuration · Troubleshooting
A self-hosted Telegram bot that fills your Navidrome music library, lets friends in, and shares music in your chats.
Preview.mp4
Navidrome is a good way to listen to your own music, but filling it is up to you. A friend sends a track in Telegram, and you copy it to the server over SSH. A friend wants in, and you create their account, pick their libraries, and upload their files. You leave a streaming service, and your likes and playlists stay behind.
Beatstash moves that work into a Telegram chat. Navidrome keeps doing the playback.
Never self-hosted music? You don't need Navidrome yet. On a fresh Linux server the installer sets up Navidrome, the bot, and HTTPS, the bot imports your streaming likes and playlists, and you listen in a phone app such as Symfonium or Amperfy.
- Add music from Telegram. Forward a track or send files from your phone. The bot fills in the tags, skips duplicates, and files the music into artist and album folders. MP3, FLAC, M4A, OGG, Opus, and WAV work.
- Bring your streaming collection. Import your likes, saved albums, and playlists from a supported service. Afterwards the bot keeps syncing what you save there.
- One server for your friends. Send an invite link, and each person gets a Navidrome account, a personal library, and a storage limit you set. Tracks they want to show the group go into a shared library.
- Share music in any chat. Type
@your_music_bot npto send what's playing, or search your library right inside a conversation. - Works with the Navidrome you have. Your music stays in its folders, and you can find and share it from Telegram.
- An installer that does the setup. It connects an existing Navidrome or installs everything from scratch, HTTPS included.
| Service | Status |
|---|---|
| Zvuk | Likes, saved albums, playlists, and sync. Needs a subscription. |
| Yandex Music, YouTube Music, Spotify | Planned |
Details are in supported sources.
You need a Linux server (AMD64 or ARM64) with Docker Compose, a bot token from @BotFather, and api_id and api_hash from my.telegram.org. The full list is in requirements.
Run the installer on the server. It walks you through Telegram setup and asks whether to connect your Navidrome or install a new one:
curl -fL https://github.com/lubaskinc0de/beatstash/releases/latest/download/install.sh -o install.sh
bash install.shRun it again in the same folder to finish an interrupted setup. Later, bash install.sh upgrade with a newer release's installer updates the installation, and bash install.sh uninstall removes it.
The documentation covers both install paths step by step, everyday use, HTTPS, and updates. To see how beatstash fits next to Navidrome and beets, read the comparison.
Bug reports and new music providers are welcome. See CONTRIBUTING.md.