QBxBot Command Channel

The Command Channel lets you operate your QuickBox Pro install from your own messaging account. You send a short command to QBxBot — your install’s own private bot — and it carries out the action and replies to you over the same chat. You can link a Discord account or a Signal account; the channel is transport-neutral, so linking and commanding work the same way on either.

QBxBot is not a shared community bot. Each install runs its own bot, dials out to your chosen messaging platform, and only ever acts on your install. Nothing is exposed to the public internet, and the bot can only run a small, fixed set of commands that an administrator has chosen to allow.

What you can do

How it works

A command travels through a fixed path, and your authority is checked at every step before anything runs:

1. You DM QBxBot from your linked account.
2. QBxBot confirms the message came from your verified account.
3. It checks that your account is allowed the command, on the app you named, for the target user (yourself, or anyone if you are an admin).
4. For any action that changes state — stopping or restarting a service, or any administrator action like banning a user or triggering a backup — it asks you to confirm before it proceeds. The two highest-impact administrator actions (banning a user and creating a user) ask for a stronger confirmation where you also have to type the target’s name back.
5. It runs the action through the same safe, internal path the dashboard uses — and replies to you with the result.

The bot can only run commands from a closed, server-defined list. There is no way to send it a free-form command or a shell command — anything that is not a recognized command is simply ignored.

Works on a home server (no port to open)

The Command Channel is outbound-only. Your install dials out to Discord or Signal to receive your commands — it never waits for an incoming connection. This is the opposite of exposing a dashboard or web app to the internet.

This applies to both Discord and Signal:

• Discord — your install opens a connection out to Discord and receives your DMs over it. Nothing listens for inbound traffic on your server.
• Signal — signal-cli on your install keeps its own outbound connection to Signal’s servers. The dashboard talks to it entirely on the local machine, never over the network.

Because nothing is exposed, there is no inbound surface to attack and no firewall rule to add. The only network traffic is your install reaching out to the messaging platform it already trusts.

Setting it up (administrators)

The admin controls for the Command Channel live on the command tab of Settings > Notifications. You turn on the install-wide master switch there, choose your command catalog, and enable each messaging platform you want to allow.

The admin tab also gives you an install-wide kill switch. Turning the channel off immediately stops QBxBot from acting on any command, for every user, on every platform, without removing anyone’s links or settings.

Command insights and audit (administrators)

The admin Command Channel tab includes a Command Insights summary and a Command activity audit log. Insights give you an at-a-glance view over a recent window — how many commands ran, how many were denied, the success rate, and which commands, users, and apps are most active. The audit log lists every individual command attempt and its outcome. Both are administrator-only; there is no equivalent user-facing alert feed.

Enabling Discord

Your install runs one Discord bot, and that single bot does everything: it receives the commands your users DM it and sends those users their alerts as DMs. The same bot token powers both directions. You set it up once.

Step by step (administrators)

You create a Discord application with a bot, copy its token, get the bot somewhere it can reach your users, and paste the token into your install. This is a one-time setup.

Bot vs webhook — what each can do

This is the single biggest point of confusion, so it is worth being explicit. A bot token and a webhook are two different things:

Enabling Signal

Signal needs three things in place: signal-cli installed on your server, a Java runtime (signal-cli is a Java application — the installer sets this up for you), and a Signal identity for QBxBot to send and receive on. The Signal settings page has an Install button that prepares signal-cli and Java for you; once that is done, you give QBxBot a Signal identity in one of two ways.

Link Device (recommended)

In the Signal settings, choose Link Device. QBxBot shows a QR code. On your phone, open Signal → Settings → Linked Devices → Link New Device and scan it. QBxBot then rides on your existing Signal account as a linked device — exactly like Signal Desktop. Your phone stays registered and fully working; nothing is taken over.

This is the best choice for a home or personal install because it needs no second phone number — it reuses the Signal account you already have.

Register Number

In the Signal settings, choose Register Number to claim a phone number for QBxBot directly. You enter the number in full international form, solve a Signal captcha in your browser when prompted, and enter the verification code Signal sends by SMS (or voice call) to that number.

After either path, turn on Signal inbound commands to arm it. QBxBot starts listening for DMs on its Signal identity, and your users can link.

Linking your account

Once an administrator has enabled the channel, each user links their own messaging account from the Command Channel section of their Profile. The link proves control of the account by having you send a one-time code from that account — you never type your account ID or phone number into a form. The steps are the same whether you link Discord or Signal.

1. Opt in. Turn on the Command Channel for your own account.
2. Choose a channel. Pick the platform you want to command from — Discord or Signal (whichever your administrator has enabled).
3. Provide a Local API Key. Choose the scope you need (read for status only, write for start/stop/restart) and paste in a matching Local API Key. The key is used once to prove install authority and is never stored or shown again.
4. Get your code. The dashboard shows an 8-digit code.
5. DM the code to QBxBot. From the account you want to command with, send the bot verify followed by your code (for example, verify 12345678). On Signal, you DM that code to your install’s QBxBot Signal number.
6. Done automatically. The dashboard is watching for that message — when QBxBot receives it from your account, the link flips to verified on its own. There is nothing else to click.

About the Local API Key

The link is bound to a Local API Key, and the key’s scope decides what your link may do:

• A read key allows status checks only.
• A write key allows start, stop, and restart (and includes read).

If you rotate or clear the bound key in API Settings, the link is disconnected automatically and you will need to link again with the new key. The dashboard shows a “needs relink” indicator when this happens. Installs that use a database-stored key (rather than an environment key) get the cleanest disconnect behavior.

Commands

QBxBot understands a fixed catalog of commands, split into two broad kinds: reads, which only report state and never change anything, and administrator actions, which change something on the install and always ask you to confirm first. Which of these you can actually run depends on what your administrator has turned on (the catalog) and on your role — see Available commands below.

Service control

These act on a specific app’s service. You always name the app, for example status sonarr or restart radarr. A regular user can only act on their own apps; an administrator can target any user’s app by adding the username (for example, restart sonarr alice).

When you send stop or restart, QBxBot replies asking you to confirm. Reply to confirm and the action runs; ignore it and nothing happens.

Status checks

These are read-only — they report your own state and never change anything, so they need only a read-scoped key and never ask for confirmation. They take no app name; QBxBot answers for everything you have.

Administrator reports

These read install-wide or per-user information and are available only to administrators. Like the status checks they are read-only and never ask for confirmation.

Administrator actions

These change something on the install and are available only to administrators. Every one of them asks you to confirm before it runs, is recorded in the audit log, and reaches the same hardened, internal path the dashboard uses — never a shell, never the public internet. They each need a write-scoped Local API Key. Each action also requires the matching administrator permission, exactly like the equivalent dashboard control.

Available commands

You do not have to guess what works. The Command Channel section of your Profile shows an Available commands list of exactly what you can run on this install — already filtered to what your administrator has exposed and what your role allows. A command whose underlying feature is not present on the install (for example, the VPN check when no VPN is set up) is shown greyed out with a short reason, so the list never offers something that would not work.

Custom aliases

An alias is your own shortcut name for a command you are allowed to run, so a longer command becomes a single word — for example, an alias called killplex that maps to restart plex. You build aliases from the Command Channel section of your Profile: pick a command from your available list, name the alias, and fill in any details it needs (such as the app). An alias is only ever a shortcut to a command you are already authorized for — it can never reach a command outside your permissions, and any confirmation a command requires (like stop or restart) still applies when you run it through an alias.

Cross-user aliases (administrators)

Administrators can build aliases that run a command against another user’s apps, from the Cross-User Command Aliases area of the admin Command Channel tab. You pick the target user and a command, and the alias is saved for that user. The command runs as you, targeting the user you chose, and only apps both you and that user have installed are offered.

QBxBot’s avatar

QBxBot ships with the official QBXWatcher mascot as its avatar. Administrators can replace it with their own image from the bot avatar slot in the Asset Management Center branding panel. Provide a square image (PNG, JPG, or WebP); it is cropped to a square for use as the bot’s avatar.

Security

The Command Channel is deliberately narrow and layered:

Disconnecting

You stay in control of your own link:

• Opt out turns the channel off for your account without removing your link — commands are simply ignored until you opt back in.
• Unlink removes the binding entirely. To use the channel again you link your account from scratch.

An administrator’s install-wide kill switch overrides everything: when it is off, no command runs for anyone.

Messaging platforms

Discord and Signal are equal, first-class ways to command your install. The command catalog, the off-until-enabled gating, the key binding, QBxBot’s avatar, and the outbound-only reachability are all the same no matter which platform you use.

• Discord — One bot powers everything. An administrator creates a Discord application with a bot, enables its Message Content intent, gets the bot into a server its users share, and pastes the bot token into the install. That single token both receives commands and sends alerts. Users then link their Discord account.
• Signal — An administrator gives QBxBot a Signal identity — by Link Device (attaching to an existing Signal account by QR scan, recommended) or Register Number (claiming a dedicated number with a captcha and SMS code) — then arms Signal. Users then link their Signal account by DMing a code to QBxBot’s number, exactly like Discord.

You can enable one platform or both. Whichever you use, linking works the same way: get a code in the dashboard, DM it from the account you want to command with, and the link verifies automatically. After that, the commands you send are identical.

Best practices

FAQ

Related pages