Introduction
Nexus Bot Manager is a self-hosted control panel for Node.js Discord bots. It exposes a web interface to manage the full lifecycle of a bot: creating it from a template, editing its code, running it as a background process, watching its logs, and updating it without taking the host down.
This documentation covers every section of the application and the most common operations. It is intentionally concise — for end-to-end instructions, see the installation guide.
Installation
Nexus is installed with a single shell command on a fresh Linux server. The official installer handles dependencies, downloads the latest stable release from GitHub, generates a unique JWT secret and registers the service.
The minimum supported distributions are:
- Debian 11 / 12
- Ubuntu 22.04 / 24.04
Other compatible Linux distributions can be used as long as Node.js 20 LTS is available.
Run the installer as root:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/Julien48003/nexus-bot-manager/main/scripts/install.sh)"
For a complete walk-through of system requirements, supported environments and the steps performed by the installer, see the Installation page.
First login
When you reach the web interface for the first time, Nexus runs a guided setup wizard. The wizard lets you configure the most important settings without having to edit files by hand:
- Pick the interface language (English, French, German).
- Create the administrator account (username and password).
- Optionally create the first Discord bot using a template.
The credentials you set here are the only credentials used to access the dashboard. Keep them safe — there is no password recovery mechanism by design (the system is self-hosted, so only you can reset it).
Dashboard
The dashboard is the home of the application. It summarises the state of your instance at a glance:
- The total number of bots and how many are currently online.
- Live CPU and RAM usage for the host.
- A list of every bot with its status and quick actions.
The sidebar gives you access to Bots, Files, Settings and other sections. The dashboard itself is a read-only overview — most actions happen in the dedicated sections.
Bot management
The Bots section is where you create, start, stop and remove bots. Each bot
is a standalone Node.js project stored under /opt/<bot-name>:
/opt/
├── bot-one/
│ ├── index.js
│ ├── package.json
│ ├── .env
│ └── node_modules/
└── bot-two/
├── index.js
├── package.json
├── .env
└── node_modules/
Typical operations available from the bot detail page:
- Start, stop and restart the bot process (managed by PM2).
- Edit the
.envfile (Discord token, channel IDs, etc.). - View bot-level resource usage (CPU, RAM).
- Open the live logs of the bot.
- Export the bot as a ZIP archive.
Templates
Nexus ships with nine ready-to-use Discord.js templates. They cover the most common needs of a community server and provide a clean starting point for more advanced projects.
| Template | Use case | Difficulty |
|---|---|---|
| Minimal | Quick start, blank bot | Beginner |
| Slash Commands | Modular architecture with REST deploy | Intermediate |
| Vérification & Règles | Auto-assign member role on rules accept | Beginner |
| Accueil & Onboarding | Welcome messages, auto-role, leave messages | Beginner |
| Tickets Support | Private channels via button | Intermediate |
| Modération | /warn, /mute, /kick, /ban, /clear | Intermediate |
| Rôles & Auto-rôles | Reaction/button roles + join auto-role | Beginner |
| Système de niveaux | XP per message, /rank command | Intermediate |
| Auto-modération | Bad words, anti-spam, anti-link filter | Intermediate |
Each template ships with:
- A complete
README.mddescribing how to configure and run it. - An
.env.examplewith every variable the template needs. - The correct Discord intents declared for its features.
Code editor
The built-in code editor is powered by Monaco — the same editor that runs inside VS Code. From the editor you can:
- Open multiple files at once (multi-tab).
- Edit with syntax highlighting, search and basic code intelligence.
- Save with Ctrl + S (or ⌘ + S on macOS).
The editor talks to the Nexus backend through a dedicated API. Edits are versioned as soon as they are saved, and any error reported by the bot is surfaced through the diagnostics panel.
File manager
The File Explorer gives you direct access to the project's files without leaving the browser. From this view you can:
- Browse the directory tree of the selected bot.
- Create new files and folders.
- Rename and delete files.
- Upload files with drag & drop or through the file picker.
File operations are locked to the project's directory — the manager cannot traverse outside of it.
npm packages
The NPM Dependencies view lists every package currently
declared in the project's package.json. From there you can:
- Install a new package by name.
- Remove an existing package.
- See the current installed version and the latest version available on npm.
npm commands through argument arrays — never
through shell interpolation. This prevents command injection through
package names or version strings.
Monitoring
The monitoring view exposes host-level metrics collected by the
systeminformation library:
- CPU — instantaneous and average load.
- RAM — used, free and total memory.
- Disk — used and total storage on the installation volume.
- Uptime — how long the host has been running.
Each bot also reports its own per-process CPU and RAM usage, which can be inspected from the bot detail page.
Logs
Nexus streams bot logs in real time through Socket.IO. The log view
combines stdout and stderr output and updates as
soon as the bot emits new lines.
The log subsystem also performs:
- Discord.js diagnostic detection (invalid tokens, missing intents, etc.).
- Detection of missing environment configuration.
- Detection of port conflicts.
- Token and secret redaction before displaying logs in the UI.
Import & Export
You can download a complete bot project as a ZIP archive (export) and upload a ZIP archive back to create or restore a bot (import). This is the recommended way to:
- Move a bot from one host to another.
- Keep a snapshot of a known-good state before a major change.
- Share an example project with someone else running Nexus.
Exports include the project files and configuration, but
node_modules/ is excluded to keep archives small. The
dependencies are reinstalled automatically on import.
PM2
Each bot is managed as a separate PM2 process. PM2 is a battle-tested Node.js process manager that gives Nexus:
- Reliable restarts on crash.
- A clean start / stop / restart API.
- Process status and resource metrics.
If you want to interact with PM2 directly from the shell, the process names match the bot names you defined in Nexus.
Settings
The Settings section is where you personalise the application. It is organised around three areas:
- Theme — switch between Light, Dark and System, and pick an accent colour from a predefined palette.
- Density — toggle a more compact layout if you prefer denser information.
- Language — switch between English, French and German. The change applies immediately to the whole interface.
Updates
Nexus can check for newer versions on its own and apply them with one click. Open Paramètres → Logiciel:
- Click Vérifier les mises à jour to detect new releases from GitHub.
- Click Mettre à jour to start the update.
- Watch the live progress and let Nexus reload automatically.
If you prefer updating from the server:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/Julien48003/nexus-bot-manager/main/scripts/update.sh)"
Both paths preserve your .env, the data/ directory and all bot folders.
Authentication
Nexus uses JWT-based authentication. A unique JWT secret is automatically generated on first launch and stored locally. Passwords are hashed with bcrypt before being stored.
The authentication flow is:
- The login endpoint accepts the username and password.
- On success, it returns a signed JWT that the client stores locally.
- Every protected API endpoint verifies the JWT before doing any work.
If you ever need to reset the administrator password, edit the
.env file on the server and restart the service — there is no
self-service password recovery by design.
Security
Nexus ships with the following application-level protections:
- JWT authentication with bcrypt password hashing.
- Login rate limiting.
- API rate limiting on public endpoints.
- Input validation on every public route.
- Bot name validation (shared by HTTP and Socket.IO routes).
- Protected file paths and directory traversal protections.
- Restricted file operations locked to the project directory.
- Security-related HTTP headers (including CSP).
- Automatically generated JWT secrets.
- An update lockfile to prevent concurrent updates.
Troubleshooting
The installer says "command not found"
The installer requires curl and bash to be available
on the host. Both come preinstalled on the supported distributions. If you
are using a minimal image, install them with the system package manager
before running the installer.
The bot stays offline after start
Open the bot's Logs view. The most common causes are:
- The Discord token is missing or invalid.
- The required Discord intents are not enabled in the developer portal.
- A missing environment variable in
.env. - A port conflict with another bot on the same host.
The web interface is unreachable after install
Verify that the Nexus service is running and that the port you are trying to reach is open in the system firewall. If you are connecting remotely, make sure your reverse proxy is forwarding requests to the local port used by Nexus.
An update fails midway
The update lockfile prevents concurrent updates, so the safest path is to wait for the previous attempt to finish. If the state is stuck, inspect the service logs on the host and rerun the update once the lock is removed.
FAQ
Is Nexus a cloud service?
No. Nexus is a self-hosted piece of software. Your bots, code, environment variables and logs stay on the host you install it on. Nexus itself does not run a cloud platform.
Do I need a Discord application to use Nexus?
You need a Discord application and a bot token for each bot you want to run. Nexus provides templates that tell you which intents to enable, but the application itself must be created in the Discord developer portal.
Can I run multiple bots at the same time?
Yes. Each bot is a separate Node.js project managed by its own PM2 process. The dashboard shows you the status of all your bots in one view.
Does Nexus sandbox bots from each other?
No. Nexus is a management platform, not a container runtime. Bots share the same Node.js and operating system as the host. If you need sandboxing, run each bot in a separate container or virtual machine.
Can I update Nexus without losing my bots?
Yes. Both update paths preserve your .env, the
data/ directory and all bot folders.
Where do I report a bug?
Open an issue on GitHub Issues and include your Nexus version, OS, Node.js version and the relevant logs. Never share Discord tokens, JWT secrets or other sensitive data.