◈ONYXDISCORD BOT
Dashboard ↗Add ONYX +
Home / Setup guides
SETUP GUIDE CENTER

Configure it with confidence.

Start with permissions and persistent storage, then test each feature in a controlled way. If a required external service is missing, the feature will not work until it is configured.

1. First-run checklist

  1. Use Node.js 22 or newer and install the dependencies from the project root.
  2. Configure environment variables in the private bot host. Keep tokens/passwords out of the public site and screenshots.
  3. Set up MongoDB if the feature needs persistent settings, Premium grants, tickets or activity records.
  4. Invite ONYX with only the permissions the enabled modules need; review its role position.
  5. Run /guide in Discord, configure a module and test it with a non-admin account.
Add ONYX

2. Discord permissions & role hierarchy

Grant View Channel and Send Messages where needed; Embed Links for embeds; Manage Roles for AutoRole; and the appropriate moderation permissions for moderation actions. Keep ONYX's role above every role it must assign or moderate, but below sensitive owner/admin roles where practical.

Do not grant Administrator simply to bypass a configuration issue. Check the exact permission denied in the Discord audit log or bot host logs.

3. Moderation & security

  1. Choose a private staff log channel and grant ONYX access to it.
  2. Configure moderation/AutoMod settings through the supported slash commands.
  3. Begin with conservative thresholds and exemptions for trusted integrations.
  4. Test a low-risk case, then confirm the action and log output.

Anti-nuke or lockdown features should be tested and permission-reviewed before enabling them in large communities.

4. Welcome messages & AutoRole

  1. Create a welcome text channel and confirm ONYX can view it, send messages and embed links.
  2. Open the dashboard, choose a server and use Welcome & Roles to edit the welcome template, target channel and optional DM.
  3. Preview text placeholders before saving. Discord can block direct messages due to member privacy settings.
  4. For AutoRole, place the bot role above the target role, then configure and test via supported bot commands.

5. Tickets & support

  1. Create a ticket category and staff role/channel with correct privacy permissions.
  2. Run the ticket setup/panel commands listed in the command reference.
  3. Test create, claim, close and transcript behaviour with non-staff and staff accounts.
  4. Keep transcript and log channels private and follow your community privacy policy.

6. Music / Lavalink v4

Music playback needs a reachable Lavalink v4 node. Set the node connection fields on your bot host, not in the website.

MUSIC_LAVALINK_HOST=your-node-hostMUSIC_LAVALINK_PORT=443MUSIC_LAVALINK_SECURE=trueMUSIC_LAVALINK_PASSWORD=your-private-password

The port/TLS settings must match your provider. Restart the bot, inspect connection logs and test /play. Never paste the actual Lavalink password into a public chat.

Music troubleshooting support

7. AI features

AI features require an API key for the provider used by the bot and any channel/personality setup the module supports. Store the key in a secret environment variable, set rate/usage limits, and test a non-sensitive prompt. This website never asks for or stores API credentials.

8. Dashboard OAuth & hosting

  1. Keep the Discord bot running on a persistent Node.js host. Netlify static hosting cannot keep a Discord Gateway connection alive.
  2. Configure a Discord OAuth application/client ID and client secret on the dashboard host.
  3. Register the exact redirect URI shown in the deployment guide; it must match character-for-character.
  4. Set a random session secret with at least 32 characters and configure the owner Discord IDs.
  5. Deploy the public marketing site separately and set its API URL to the dashboard origin to enable the live public offer counter.

9. Premium request & approval flow

  1. Member signs in with Discord and chooses a server they can manage.
  2. The backend reserves one of the first 10 launch slots or validates an active owner-created promo code.
  3. A request is saved in MongoDB, and the configured Premium request channel and owner DMs are notified where reachable.
  4. Owner independently verifies payment, then approves or rejects using owner-only controls.
  5. Approval saves the bot-compatible entitlement and the dashboard notification/status updates. Rejected requests release reserved launch/promo capacity.

No payment gateway is configured in this release. Approval is manual and must not be treated as proof that a payment happened.

10. Common troubleshooting

Dashboard says OAuth is not configured

Check client secret, callback URL and session secret; restart the bot host. Ensure the exact callback URI exists in the Discord Developer Portal.

The server does not appear in the dashboard

The account needs Manage Server/Administrator in Discord and the bot must be present in that server. Refresh server selection after inviting the bot or changing access.

Premium request cannot be submitted

Confirm MongoDB is reachable and correctly configured, then check the bot host logs. A request is not accepted until the API returns its request ID.

Owner DM was not received

Discord may block DMs or the owner may have disabled DMs from shared servers. Configure the private Premium request channel as a fallback and inspect host logs.

Music node won't connect

Confirm Lavalink v4 host, password, port and TLS settings match the provider. Never expose credentials in public logs.