Velox Bot

Velox is a Discord bot written in Go, backed by PostgreSQL. It covers server security (anti-raid and anti-nuke), support tickets, moderation, leveling, music, meeting rooms, scheduling, Twitch alerts and a few games. Every module is off until a server turns it on.

This repository is the bot, and it is the only open source part of Velox. The web dashboard and its API, which the hosted Velox uses, are separate proprietary software and are not part of this repository or its license. The bot does not need them: everything in the command reference works on its own, with PostgreSQL as its only dependency.

The dashboard and the bot meet in the database. The dashboard writes settings and requests into tables, and the bot reads them (and is woken through Postgres NOTIFY where it has to react at once). Those tables are documented, so you can change the same settings with SQL, or build your own tool on top. See Architecture and Database.

Documentation

This README is the front page. The rest of the documentation lives in docs/, organised like a wiki:

Page	What is in it
Getting started	Requirements, creating the Discord application, configuration, database, running locally
Host your own bot	A step-by-step guide to running your own copy on a server, with Docker Compose
Deployment	Docker, Compose, upgrade order, backups
Architecture	How the code is laid out, how an interaction flows through it, background loops, how a dashboard talks to the bot
Features	What each module does and how it behaves
Command reference	Every slash command, its options and who may run it
Database	Who owns the schema, the tables, the NOTIFY channels, how to change them
Development guide	How to add commands, subcommands, buttons, events, background jobs, settings and tables; testing; code style
Beta features	How features are tried by a few testers before release
Troubleshooting	Common problems and what they mean

Quick start

You need Go (the version in go.mod), PostgreSQL 16 or newer, and a Discord application with a bot token.

git clone <this repository>
cd velox-bot
# create .env with BOT_TOKEN, APP_ID, GUILD_ID, DB_HOST and TWITCH_CLIENT_ID (see docs/getting-started.md)
docker compose up -d db     # PostgreSQL on localhost:5432
psql "postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable" -f schema.sql
go run .

On start the bot registers its slash commands in the server named by GUILD_ID (or globally if that is empty). The full walkthrough, including the Discord side, is in Getting started.

What it does

• Security: Join Gate, raid mode, anti-nuke with quarantine, lockdowns, snapshots and restore, and a spam "heat" system, modelled on Wick.
• Tickets: a panel with categories, a private thread per ticket, claim and close, transcripts to a log channel.
• Moderation: purge, timeout, kick, ban, unban, slowmode, plus server logs for edits, deletes, joins, leaves, role changes, bans and mod actions.
• Leveling: XP per message, level cards, leaderboard, role rewards.
• Music: Lavalink-powered playback with a queue, controlled from Discord.
• Meeting rooms: join a lobby voice channel and get a temporary room you can lock and invite people to.
• Scheduling and projects: 1:1 sessions with DM invites and reminders, and a simple project list.
• Twitch alerts, welcome messages, default role: per-server setup through /config.
• Fun: /ping, /joke, /coinflip, /dice, /rps with stats and a leaderboard.

When the bot joins a server for the first time, toggleable systems start disabled and the person who invited it gets a DM with setup instructions.

Repository layout

main.go                     wiring: config, database, repos, services, bot
internal/config             environment variables
internal/bot                Discord session, intents, event registration, startup
internal/commands           slash commands, one package per feature, plus the dispatcher
internal/events             handlers for gateway events and background loops
internal/db                 connection, repos (SQL), services (rules)
internal/security           anti-raid and anti-nuke engine
internal/tickets            ticket flows
internal/music              Lavalink player, queue, buttons
internal/beta               beta access gate
internal/modlog, rankcard   small shared helpers
schema.sql                  mirror of the tables the bot reads and writes

Host your own bot

You can run your own copy under your own Discord application. Host your own bot walks through it on a fresh server with Docker Compose: creating the application and the invite link, configuring the bot, loading the database, optional music and Twitch, backups and updates.

Contributing

Contributions are welcome: bug reports, fixes, documentation and new features.

• Read CONTRIBUTING.md first. It covers how to report a problem, how to propose a change, and what a good pull request looks like.
• The Development guide shows how to add a command, a button, an event handler, a setting or a table, and how to test them.
• For anything big, open an issue to talk about it before you write the code.
• Pull requests go to the dev branch. Before opening one, run gofmt on the files you touched and go build ./... && go vet ./... && go test -race ./....

License

Velox Bot, the code in this repository, is released under the Apache License 2.0. Copyright 2026 Fernando Videira. See NOTICE. The license does not cover the proprietary Velox dashboard and API, or the Velox name and logo as used by the hosted service. The libraries the bot uses are under their own permissive licenses (see go.mod).