View on GitHub Install Nexus
Documentation

How to use Nexus Bot Manager

A practical reference for every section of the application — installation, configuration, day-to-day bot management, security and troubleshooting.

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.

Self-hosted software. Nexus is not a cloud service. Your bots, code, environment variables and logs stay on your own infrastructure. Nexus never sends your data anywhere.

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 · install
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 .env file (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.
Important. Nexus is a management platform, not a container runtime. Bots managed by Nexus are not automatically isolated from each other like containers or virtual machines.

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.

TemplateUse caseDifficulty
MinimalQuick start, blank botBeginner
Slash CommandsModular architecture with REST deployIntermediate
Vérification & RèglesAuto-assign member role on rules acceptBeginner
Accueil & OnboardingWelcome messages, auto-role, leave messagesBeginner
Tickets SupportPrivate channels via buttonIntermediate
Modération/warn, /mute, /kick, /ban, /clearIntermediate
Rôles & Auto-rôlesReaction/button roles + join auto-roleBeginner
Système de niveauxXP per message, /rank commandIntermediate
Auto-modérationBad words, anti-spam, anti-link filterIntermediate

Each template ships with:

  • A complete README.md describing how to configure and run it.
  • An .env.example with 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.

Sandbox. The editor only has access to files that belong to the selected bot. It cannot read or modify files outside the project's directory.

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.
Safe by design. Nexus executes 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.
Privacy. Even though they may appear in your terminal, Discord tokens and other secrets are redacted from the log view by default.

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:

  1. Click Vérifier les mises à jour to detect new releases from GitHub.
  2. Click Mettre à jour to start the update.
  3. Watch the live progress and let Nexus reload automatically.

If you prefer updating from the server:

bash · update
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.
Operational security. These protections reduce the application's attack surface, but security also depends on the configuration of the underlying operating system, network and reverse proxy. For an installation exposed to the Internet, HTTPS and a properly configured reverse proxy are recommended.

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.