Installing QuickBox Lite
On a fresh Debian 13 server, the QuickBox Lite installer sets up qBittorrent, nginx, a web dashboard and a browser terminal, all behind one password, in about 14 minutes by its own clock, and right after the install the whole server used 414 MiB of RAM. A minimal Debian 13 image hit two problems before the first dialog appeared; Step 1 and Step 3 show the fixes. Where QuickBox Lite comes from, its licence (GPL-3.0) and its module catalogue are on the QuickBox Lite page. This guide is one Pulsed Media run on 29 October 2026, on a 6 vCPU, 3 GB, 32 GB-disk VM on a shared test host, with the dialogs answered in a terminal session.
Requirements
| Item | Requirement |
|---|---|
| Operating system | Debian 13 (trixie), the version this run used. Other supported releases, virtualisation types and the README's hardware minimums are under Supported systems. |
| Access | A root shell. The wrapper exits with "You do not have root privileges" for any other user. |
| Packages | curl to fetch the script and whiptail for the dialogs. A minimal Debian 13 image may lack whiptail, and the installer does not add it (see Step 1).
|
| Tested on | VM with 6 vCPU, 3 GB RAM and a 32 GB disk, Debian 13 (trixie) minimal template, QuickBox Lite master at commit e0b522b ("sync from upstream, version bump"), 29 October 2026 |
Step 1: Prepare the server
On a new Debian 13 server, log in as root over SSH and add whiptail first:
apt-get update apt-get install -y whiptail curl
On the test VM, a minimal Debian 13 template, whiptail was missing. The installer's setup script needs it for every dialog but does not install it, so the first run stopped at the shell with four lines of whiptail: command not found. Installing it first avoids that stop.
The test VM was named seedbox, and the self-signed certificate the installer made came out as CN=seedbox.example.com. Set the server's name before the install if the certificate name matters to you.
Step 2: Download the installer and read it
The README one-liner runs the script straight from the network. Saving it to a file first lets you look at it before it runs as root:
curl -fsSL -o qbl-setup.sh https://git.io/qbox-lite less qbl-setup.sh
git.io/qbox-lite redirects to onekey.sh in the amefs/quickbox-lite repository, a 100-line "One Key Installation wrapper". It runs apt-get update and apt-get upgrade, installs git, lsb-release, dos2unix and screen, deletes any existing /etc/QuickBox, clones the quickbox-lite repository there and starts /etc/QuickBox/setup.sh inside a screen session named qbox-install. Those 100 lines are the launcher only; the real installer arrives with the clone. Because it deletes /etc/QuickBox first, run the wrapper once; to restart an interrupted setup, run the setup script directly (Step 3).
Step 3: Run it, and watch the system upgrade
bash qbl-setup.sh
The wrapper upgrades the installed packages before the first dialog. On the test VM that upgrade included a new grub-pc package, which asked for "GRUB install devices:" as a plain text prompt, not a dialog. Its automatic grub-install then failed:
grub-pc: Running grub-install ... You must correct your GRUB install devices before proceeding: DEBIAN_FRONTEND=dialog dpkg --configure grub-pc dpkg --configure -a dpkg: error processing package grub-pc (--configure):
On that VM (BIOS boot, one disk, /dev/sda) these three commands fixed it:
grub-install /dev/sda update-grub dpkg --configure -a
The cause of the failed grub-install was not traced. It comes from apt upgrade on that image, not from QuickBox Lite, and a server with no pending grub-pc upgrade will not see it. Check the disk name with lsblk before running grub-install on your own server.
The wrapper does not stop on a failed upgrade: it went on to clone the code and start setup, which on the test VM then stopped on the missing whiptail. After fixing grub (and installing whiptail), start the setup script directly rather than the wrapper:
bash /etc/QuickBox/setup.sh
Step 4: Answer the dialogs
QuickBox Lite's dialogs, in sequence: Installation Language, Welcome, Manual (key help), Disclaimer, Log, Domain, Hostname, SSH Port, Create an Admin account (username, then password), FTP, Theme, Timezone, source.list, Software CDN, Auth Provider, Install Software, Public Trackers, BBR, Auto Reboot, then a summary. The Welcome message is in the setup script but was not captured on the test recording. The Manual dialog spells out the keys: Tab or the arrows between buttons, Space to mark, Enter to accept.
/root/quickbox.<pid>.log.
The test run answered No to FTP.
The test run answered No to Timezone, to replacing the default source.list and to changing the default software CDN.
The test run answered No to blocking public trackers.
The test run answered No to Auto Reboot. The summary screen that comes next shows the admin password in plain text. Do not record or share that screen, and clear the terminal scrollback after the install:
clear && printf '\033[3J'
Step 5: Let the install finish
From the summary screen on, QuickBox Lite works unattended until the Finish dialog, which states how long it took.
On a reboot test afterwards, SSH answered again after about 30 seconds; nginx, qBittorrent, the dashboard's websocket service and the web console all came back, and no systemd unit had failed.
Step 6: Log in to the dashboard and qBittorrent
Browse to https://seedbox.example.com/ or the IP address. Past the self-signed certificate warning comes an nginx basic-authentication prompt; sign in with the admin account from Step 4.
From another host on the test network, every protected path answered HTTP 401 without credentials: the dashboard /, its websocket /ws, qBittorrent's web UI /qbittorrent/, the web console /seedadmin.console/ and the downloads path /seedadmin.qbittorrent.downloads/. The last two carry the admin user's name.
To check the client end to end, the run queued the Debian 13.7.0 netinst torrent through qBittorrent's web API: 53% after 45 seconds, about 9.6 MB/s, 86 seeds. Read that as the test network's speed, not a QuickBox Lite benchmark.
The web console's systemd unit starts it like this, as the admin user:
/usr/local/bin/ttyd -i 127.0.0.1 -p 4200 -W bash
It listens on loopback only; the password in front of it is nginx's.
What the install produced
Figures from right after the install, before the test torrent, unless a row says otherwise.
| Measure | Result |
|---|---|
| Debian packages | 385 before, 584 after. The after count includes tmux and its dependencies, added for the recording, so the installer's own share is about 195. |
| RAM in use, whole VM | 414 MiB, including the recording's tmux session (8 MiB). 267 MiB on the fresh VM before the install; 505 MiB a few minutes later, after a test torrent had been added. |
| Dashboard websocket service (node) | 70 MiB resident, runs as root |
| qbittorrent-nox (v4.6.7) | 32 MiB resident, runs as the admin user (one systemd service per user) |
| Root filesystem used | 3.6 GiB (2.2 GiB before the install) |
| Admin user's home directory | mode 755 |
| TLS certificate | self-signed, CN=seedbox.example.com, valid until October 2036
|
Open TCP sockets after the install, from ss -tlnp (UDP was left unmeasured):
| Listening on | Service |
|---|---|
| All addresses, ports 80 and 443 | nginx |
| All addresses, port 22 | SSH (kept on 22 in Step 4) |
| Each interface address, peer port (7079 on the test VM) | qBittorrent, for BitTorrent peers |
| 127.0.0.1 only (port 15187 on the test VM) | qBittorrent |
| 127.0.0.1 only, port 8575 | dashboard websocket service (node) |
| 127.0.0.1 only, port 4200 | ttyd web console |
| 127.0.0.1 only, port 25 | exim mail server, already on the Debian template before the install |
What the installer leaves to you
The test server had a single admin account. The rows below are what to revisit before a second person gets a login, the first two above all.
| Area | State on the test VM | What to do |
|---|---|---|
| Dashboard on localhost | /etc/nginx/apps/dashboard.conf has satisfy any; allow 127.0.0.1; deny all; before auth_basic, so a request from 127.0.0.1 gets the dashboard without a password (HTTP 200 from inside the VM, 401 from outside) |
On a server with other local users or untrusted processes, treat the dashboard as open to them, or remove the localhost exemption. |
| /proc | Mounted without hidepid, so every user can list every other user's processes and their command lines |
Before adding accounts, look at hidepid=2, and try it on this server first rather than assuming it works.
|
| Password files | /etc/htpasswd and /etc/htpasswd.d/htpasswd.seedadmin are mode 644, readable by every local account |
Restrict them so only root and the web server can read them. |
| Home directory | /home/seedadmin is mode 755 |
Tighten it (for example 750) if other users share the server. |
| Firewall | With the answers above, the installer added no firewall rules; iptables policies ACCEPT. Per the setup script, answering Yes to FTP inserts one ACCEPT rule for passive ports 10090-10100. | Write rules from the console or with a way back in. Let through loopback and established traffic, your SSH port (22, or 4747 if chosen), 80, 443 and qBittorrent's peer port on TCP and UDP, and drop everything else. Not tested on this run. |
| TCP | Congestion control cubic; BBR was offered and left off |
Measure throughput before switching. |
Gotchas and troubleshooting
whiptail: command not found
The setup script draws every dialog with whiptail and does not install it. On a minimal Debian 13 image the first run printed whiptail: command not found four times and returned to the shell. Install it and start the setup script again:
apt-get install -y whiptail bash /etc/QuickBox/setup.sh
GRUB install devices prompt during the upgrade
See Step 3. The prompt is a plain text question in the middle of apt output, easy to miss in a scrolling terminal; the failed grub-install after it leaves dpkg with an unconfigured package until it is fixed.
SSH moved to 4747
The SSH Port dialog has 4747 pre-selected. Per the setup script, choosing it writes Port 4747 to /etc/ssh/sshd_config.d/10-quickbox.conf, so after the install connect with ssh -p 4747, and open that port in any firewall before you close your current session. The test run kept port 22 (sshd config: Port not set, so 22), so the 4747 path was not tested.
qBittorrent version label is wrong
The checklist says qBittorrent v4.2.5; qbittorrent-nox --version on the test VM printed qBittorrent v4.6.7. Check the installed version rather than trusting the label; this guide did not check the other entries' labels.
Plain HTTP redirect shows backslashes
Port 80 answers with a 301 whose Location header, as curl showed it, contains literal backslashes, in the form https://\address\/. The cause is line 14 of /etc/nginx/sites-enabled/default:
return 301 https://\$host\$request_uri;
Browser behaviour was not tested. Open the https:// address directly, or remove the two backslashes from that line and reload nginx (not tested on this run).
The password shows on the summary screen
The last screen before the install starts prints the admin password in plain text. On a recorded terminal, a screen share or a shared tmux session, anyone watching gets it. Clear the scrollback afterwards (Step 4).
FAQ
Can I use Let's Encrypt instead of the self-signed certificate?
The Domain dialog offers it during the install. Per the setup script, Yes asks for the domain and checks that its A record matches the server's public IP, looked up through public what-is-my-IP services and Cloudflare's DNS-over-HTTPS resolver, before going on. The test run answered No, so this guide did not test it.
Does it install rTorrent or Deluge too?
Both are on the Install Software checklist, along with Transmission, mktorrent and filebrowser, and more torrent tools and web UIs are among the install modules listed under Applications. Of the torrent clients, the test run installed qBittorrent only.
Should I enable BBR?
The installer leaves it off unless you choose it. Measure your throughput on cubic first, then compare; this guide did not test BBR.
Rather not run the server?
On a self-run QuickBox Lite server the whiptail and grub detours, the localhost exemption and the 644 password files all land on you. A Pulsed Media seedbox starts with PM Software Stack (PMSS) installed, updated and monitored, support included, on Pulsed Media's own Finnish datacenter hardware; seedboxes have been its business since 2010. For your own hardware, Installing PM Software Stack covers a self-hosted PMSS on Debian 12.
See also
- QuickBox Lite — the project behind this installer: QuickBox Community Edition roots, versions, install modules
- Installing swizzin — the same test, run with the swizzin installer on Debian 12
- Swizzin — background of the swizzin project, which also credits QuickBox
- PM Software Stack — Pulsed Media's GPL-3.0 seedbox platform
- Installing PM Software Stack — PMSS on your own Debian server
- QBittorrent — the client ticked on the Install Software list in Step 4