Self-hosting guide

Get Harmonix running.

Harmonix runs on your own machine — the bot, the music engine, and the web dashboard all start together. This walks you through it from an empty folder to a live bot.

About 15 minutes · beginner friendly
Before you start

What you'll need

Node.js 20 LTS

The runtime Harmonix is built on. Grab the LTS build from nodejs.org.

Java 17+

Lavalink v4 (the music engine) runs on Java. Any 17-or-newer JDK works — Temurin is a solid pick.

A Discord application

Free from the Developer Portal. You'll get a bot token and client ID.

A Cloudflare account

Optional but recommended — it gives the dashboard login a stable URL that survives restarts.

1

Create your Discord bot

Head to the Developer Portal, hit New Application, and name it Harmonix. Then:

  • Open the Bot tab and press Reset Token — copy the token somewhere safe. You'll only see it once.
  • Scroll to Privileged Gateway Intents and switch on Server Members and Message Content.
  • On the OAuth2 tab, copy your Client ID — you'll need it for both config and the invite link.

Keep the token private. Anyone with it can run your bot. If it ever leaks, reset it — the old one dies instantly.

2

Install Harmonix

Unzip the Harmonix folder wherever you'd like it to live, open a terminal in that folder, and pull in the dependencies:

terminal
# from inside the Harmonix folder
npm install

That installs everything the bot and dashboard need. Lavalink comes bundled — no separate download.

3

Configure it

Copy the example config to .env and fill in the two values from step 1:

.env
DISCORD_TOKEN=your-bot-token-here
CLIENT_ID=your-client-id-here

# dashboard
DASHBOARD_PORT=3000
DASHBOARD_URL=https://harmonix.yourdomain.com
SESSION_SECRET=any-long-random-string

Leave DASHBOARD_URL as-is for now if you're skipping the tunnel — you can point it at http://localhost:3000 and log in locally.

4

Set up the tunnel (recommended)

The dashboard login uses Discord OAuth, and Discord needs a fixed redirect URL. A named Cloudflare tunnel gives you one that doesn't change when you restart:

terminal
cloudflared tunnel login
cloudflared tunnel create harmonix
cloudflared tunnel route dns harmonix harmonix.yourdomain.com

Then add the redirect back on the Discord OAuth2 tab:

  • Redirect URL: https://harmonix.yourdomain.com/auth/callback
  • Match it exactly in your .env DASHBOARD_URL.

This is the #1 login gotcha. If the redirect URL in Discord and the one Harmonix sends don't match character-for-character, login just fails. A named tunnel fixes it for good — random quick-tunnel URLs change every restart and break it.

5

Launch

One command starts everything — Lavalink, the bot, and the dashboard, in the right order:

terminal
node run.js

On Windows, run the tray launcher instead and Harmonix tucks into your system tray — right-click to start, stop, or open the dashboard:

terminal
node tray.js

When you see the bot come online in your terminal, you're live. Open DASHBOARD_URL in a browser and log in with Discord.

6

Invite the bot & deploy commands

Slash commands deploy globally on first launch — no extra step. To add the bot to a server, use an invite link with your client ID:

invite link
https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=277083450646&scope=bot+applications.commands

Swap in your client ID, open it, pick a server, and confirm. Global commands can take a few minutes to show up the first time — after that they're instant.

When something's off

The usual suspects, and the quick fix for each.

Dashboard login fails or loops back +
Almost always a redirect mismatch. Check that the OAuth2 redirect in the Discord portal is exactly DASHBOARD_URL + /auth/callback. If you're on a random quick-tunnel URL, it changed on restart — switch to a named tunnel (step 4) so the URL stays put.
Music won't play +
This is Lavalink. Confirm Java 17+ is installed (java -version) and that Lavalink actually started in the terminal output. If the port's taken, change it in application.yml and restart.
Slash commands aren't showing +
Global commands can take a few minutes to propagate the first time. Give it up to an hour, then reload Discord. Double-check the bot has the applications.commands scope from the invite link.
Bot is online but ignores commands +
Usually a missing intent. Go back to step 1 and make sure Message Content and Server Members are both switched on in the Developer Portal, then restart.

That's it — you're hosting Harmonix.

Open the dashboard and start running your server from the browser.

Open the dashboard