Medusa/Setup Guide

Setup Guide

Install Medusa, run the setup wizard and get your bot online.

Medusa is set up in the browser. You start it once, open the dashboard and a setup wizard walks you through the rest. There is nothing to fill in by hand.

Before You Start

You need:

A host that runs Node.js 22 or newer, or Bun.
An empty PostgreSQL, MySQL or MariaDB database.
A Discord application with a bot, from the Discord Developer Portal.
Your Medusa license key from the Zero Development Discord.

Hosting

Option	Best for
Game panel (Pterodactyl)	The easiest choice. The panel keeps Medusa running and gives you a console and file manager.
Linux VPS or dedicated server	Full control. Use a process manager such as PM2 or systemd.
Your own computer	Testing and development.

Haven Development hosts Medusa on Pterodactyl. Buying the Setup & Installation add-on on BuiltByBit gets you 15% off your hosting for as long as you keep it.

Install

Create a server with a Node.js 22 egg.
Upload the Medusa files.
Set the startup command to node index.js.
Start the server.

On the first start Medusa creates config.json, builds the dashboard and serves it on port 3000. It does not connect to Discord yet.

Discord Application

Set these up in the Discord Developer Portal before running the wizard.

Privileged Intents

Every bot Medusa runs needs all three privileged intents.

Open your application and go to Bot.
Under Privileged Gateway Intents, turn on Presence Intent, Server Members Intent and Message Content Intent.
Click Save Changes.

Privileged gateway intents

Medusa will not start a bot with an intent turned off. It prints which ones are missing and stops. The wizard checks the token for you and shows the same steps.

Go to OAuth2 and add your dashboard address followed by /api/auth/callback/discord under Redirects:

On your own computer: http://localhost:3000/api/auth/callback/discord
On a domain: https://medusa.example.com/api/auth/callback/discord

OAuth2 redirect

Setup Wizard

Open http://localhost:3000, or your server's address on port 3000. The wizard has these steps:

Step	What you enter
Welcome	Nothing. If you used Medusa before, import your old configuration here.
Bot	Bot ID, bot token and your server ID. The token and intents are checked.
License	Your license key. The person who bought it becomes the dashboard owner.
Database	Type, host, port, user, password and database name. Click Test Connection.
Discord App	Client ID and client secret from the OAuth2 page. Click Test Credentials.
Branding	Dashboard name, icon and accent color.
Appearance	Theme, accent and login layout.
Language	The language for the bot and dashboard.
Extras	Console and logging options.
Updates	Automatic updates, modules to exclude and modules to freeze.
Finish	Review and click Finish Setup.

Medusa then saves your settings, activates the license, loads modules, connects to Discord and uploads its emojis. The wizard shows each stage with the live console and opens the dashboard when it is done. There is no restart.

The wizard remembers your progress in the browser, so a refresh or restart brings you back to the same step.

The license owner always has full access. Use the Permissions page to give other staff access. See Core.

Hosting on a Domain

Point a reverse proxy at each port, then set Dashboard URL and API URL under Settings > Server URLs. Pick yours:

Caddy gets and renews HTTPS certificates on its own. Add this to your Caddyfile and reload Caddy.

/etc/caddy/Caddyfile

medusa.example.com {
    reverse_proxy 127.0.0.1:3000
}

api.medusa.example.com {
    reverse_proxy 127.0.0.1:3001
}

Terminal

sudo systemctl reload caddy

The dashboard URL, the address in your browser and the redirect in the Developer Portal must all match. If they do not, sign-in fails with Invalid origin.

Signing In

Open the dashboard and click Continue with Discord. Staff only see the pages their rank allows.

PreviousWhat is Medusa?NextDashboard