Getting Started with QuickBox Pro
QuickBox Pro v3.2.2
The complete media server management system
This comprehensive guide will walk you through installing QuickBox Pro on your server, from system preparation to your first login and beyond.
Why Choose QuickBox Pro?
⚡ 5-Minute Setup
Get your complete media server infrastructure running in minutes with automated installation
🔒 Secure by Default
Built-in SSL, WebAuth, sandboxed services, and comprehensive security hardening
🎯 Zero Configuration
Applications are pre-configured with optimal settings - just install and use
🔄 Automatic Updates
Keep your system secure and up-to-date with built-in update management
Supported Operating Systems
Supported Distributions
- Debian 13 (Trixie)New!
- Debian 12 (Bookworm)Recommended
- Debian 11 (Bullseye)EOL June 2026
- Ubuntu 22.04 LTSFully supported
End of Life
- Debian 10 (Buster)EOL June 2024
Debian 11 reaches end of life support in June 2026. Debian 10 upstream repositories (e.g., php.sury.org) may cause installation failures. QuickBox is not responsible for third-party repository availability.
Recommended Distribution
We recommend using Debian 12 (Bookworm) or Debian 13 (Trixie) for new installations. They offer the best balance of stability and modern package versions. Learn more about Debian releases at wiki.debian.org/LTS .
Prerequisites
💿 Fresh OS Installation
Ubuntu 22.04+ or Debian 11+ (Debian 12/13 recommended for best results)
👤 Root Access
Required for system modifications and service configuration
💻 Minimum Hardware
2GB RAM (4GB+ recommended), 20GB disk space, stable internet connection
🔑 QuickBox Pro API Key
Get your unique API key from your QuickBox account dashboard
Fresh Installation Required
QuickBox Pro should be installed on a fresh, minimal server installation for optimal compatibility and security. Installing on existing systems with pre-configured services is not recommended and may cause conflicts.
Username & Password Guidelines
Usernames: Avoid usernames that begin or end with numbers, contain uppercase letters, or use reserved names like none, admin, root, user, or username. The none username in particular will fail with applications like rtorrent that use screen.
Passwords: During initial setup, avoid special characters like !, \, /, +, @, and % as they can cause escaping issues. You can change to a stronger password with these characters after installation via the dashboard.
Installation
Step 1: Elevate to Root
Switch to the root user and navigate to the /root directory:
sudo -iWhy elevate to root?
Root access is required to modify system files in /root and perform critical tasks like configuring Nginx, PHP, and system services.
If sudo is not installed:
Some OS installations don’t include sudo by default. If you receive a “command not found” error, install it as root:
apt-get install -y sudoWhy is sudo not installed by default?
This is determined by OS installation parameters. If a root password is specified during installation, sudo is not installed.
If no root password is set, sudo is automatically installed. This can also vary by provider.
Step 2: Update Your System
Ensure your system’s package lists are up to date and install any available upgrades:
apt-get -y update && apt-get -y upgradeWhy update?
Updating ensures you have the latest software packages and security patches installed. It’s a good practice to regularly update your system.
Step 3: Download the Setup Script
Fetch the latest QuickBox Pro setup script from GitHub:
curl -sL "https://github.com/QuickBox/pro-v3/raw/refs/heads/main/qbpro_v3" > qbpro && chmod +x qbproIf curl is not found:
Install curl with the following command:
sudo apt-get install -y curlWhat is curl? curl is a command-line tool used to download files from the internet.
It’s essential for fetching the QuickBox Pro installer script.
Step 4: Run the Installer
Run the setup script, providing your USERNAME, PASSWORD, and API_KEY:
./qbpro -u USERNAME -p 'PASSWORD' -k 'API_KEY'Required Parameters:
-u USERNAME: Your desired QuickBox username-p 'PASSWORD': Your desired password (use quotes for special characters)-k 'API_KEY': Your unique API Key from your QuickBox account
Get Your API Key
Your API Key is available in your QuickBox account: v3.quickbox.io/dashboard/api-keys
Advanced Installation Options
Customize your installation with these optional flags:
-d, --domainDomain name for your server (enables automatic SSL)
-d 'mydomain.com'-e, --emailEmail for notifications and SSL certificate registration
-e 'my@email.com'-dns, --dnsOpt-in DNS-01 challenge flow for wildcard/advanced SSL
-dns--dns-providerPre-select DNS provider for automated challenges
--dns-provider cloudflare--dns-credentialsPath to a KEY=VALUE credential file (non-interactive)
--dns-credentials /root/dns.env-ftp, --ftpCustom FTP port for enhanced security
-ftp 5757-ssh, --ssh-portCustom SSH port (security best practice)
-ssh 4747-t, --trackersTracker control: 'allowed' or 'blocked'
-t blockedAdvanced Installation Example
./qbpro -u USERNAME -p 'PASSWORD' -k 'API_KEY' -d 'mydomain.com' -e 'my@email.com' -ftp 5757 -ssh 4747 -t blockedThis example installs QuickBox Pro with enhanced security and automation:
🌐 Domain Setup
Automatic SSL certificate via Let's Encrypt on your domain
📧 Email Notifications
System alerts and SSL certificate renewal notifications
🔐 Custom Ports
Enhanced security with non-standard FTP and SSH ports
🚫 Tracker Control
Block or allow public trackers based on your preference
Domain Setup
If using the -d flag, ensure your domain is registered and DNS records are properly configured before installation. Combine -d with -dns when you want the installer to run a DNS-01 challenge (for wildcard or provider-restricted domains) and be ready to supply API credentials for your DNS provider.
Automating DNS Challenges (Wildcard SSL)
Need a wildcard certificate or prefer DNS-01 validation? Add the -dns flag to explicitly opt into the DNS credential workflow. The installer keeps the prompts hidden unless -dns is present, so you stay in control of when API tokens are requested.
- Interactive installs: Run the installer with
-dns(and-d yourdomain.com). You’ll be guided through selecting a supported provider (Cloudflare, Route53, Namecheap, etc.) and entering the requiredKEY=VALUEpairs. Credentials are stored securely viaqb dns-credentials <provider>and reviewed once more before Let’s Encrypt runs. - Non-interactive/automated installs: Provide everything up front with
-dns --dns-provider <provider> --dns-credentials '/path/to/file' --non-interactive. The credentials file should contain the provider’s expected variables (oneKEY=VALUEper line). Missing inputs stop the installer with clear rollback codes.
./qbpro -u USERNAME -p 'PASSWORD' -k 'API_KEY' -d 'media.example.com' -dns./qbpro --non-interactive -u USERNAME -p 'PASSWORD' -k 'API_KEY' \
-d 'media.example.com' -dns --dns-provider cloudflare --dns-credentials '/root/cloudflare.env'Updating DNS Credentials
You can update or rotate credentials at any time after installation with qb dns-credentials <provider>, and the installer will honor whatever is already stored when reissuing certificates.
One-Command Installation
./qbpro --non-interactive -u USERNAME -p 'PASSWORD' -k 'API_KEY' \
-d 'media.example.com' -dns --dns-provider cloudflare --dns-credentials '/root/cloudflare.env'For convenience, you can run everything in a single command. Update the variables and execute:
username="ENTER_DESIRED_USERNAME_HERE"
password="ENTER_DESIRED_PASSWORD_HERE"
email="ENTER_EMAIL_HERE"
api_key="ENTER_API_KEY_HERE"
(
cd /root; \
apt-get -y update && apt-get -y upgrade && apt -y install curl; \
curl -sL "https://github.com/QuickBox/pro-v3/raw/refs/heads/main/qbpro_v3" > qbpro && chmod +x qbpro; \
./qbpro -u "${username}" -p "${password}" -e "${email}" -k "${api_key}"
)This command:
- Changes to the
/rootdirectory - Updates system packages
- Installs curl if not present
- Downloads the QuickBox Pro installer
- Runs the installation with your credentials and email
Post-Installation
Access Your Dashboard
Once installation completes, access your QuickBox Pro dashboard:
🌐 Navigate to Dashboard
https://your-server-ip or https://your-domain.com
🔑 Log In
Use the username and password you created during installation
🚀 Start Installing
Browse 60+ applications and install with one click
Explore the Dashboard
The QuickBox Dashboard provides a user-friendly interface for managing applications, viewing system stats, and controlling services. You can also install applications, manage users, and configure settings—all from the web interface.
Next Steps
Installation Complete! 🎉
Congratulations! QuickBox Pro is now installed. Here are your essential first commands:
❓ qb -h
View the complete help manual with all available commands and options
📦 qb install [app]
Install any of 60+ applications (e.g., qb install sonarr -u username)
🔧 qb support enable
Enable support access for troubleshooting assistance from staff
📰 qb news
View QuickBox news, updates, and important announcements
Essential Commands Reference
# View the complete help manual
qb -h
# Install an application for a user
qb install sonarr -u yourusername
# Enable support access (for troubleshooting)
qb support enable
# View QuickBox news and updates
qb news
# Check for QuickBox updates
qb update check
# Update QuickBox to latest version
qb update quickboxPro Tip: Use qb help [command]
Need more info on a specific command? Use qb help [software_name] for detailed help on any application or qb -v to enable verbose mode for debugging.
Quick Reference: Common Tasks
👤 User Management
qb user create -u NAME -p PASS -e EMAIL🔒 Change Password
qb user password -u NAME -p NEWPASS🧹 Clean Memory
qb clean memory🔧 Fix Permissions
qb fix home -u USERNAME💾 Backup App Config
qb manage software -o backup -u NAME -s APP🌐 Set Language
qb manage lang -o enAdvanced User Reference
For seasoned administrators, here’s a comprehensive quick reference of commonly used commands:
User Management Commands
# Create a new user
qb user create -u USERNAME -p PASSWORD -e EMAIL
# Delete a user
qb user delete -u USERNAME
# Ban/Unban a user (disables services without deleting data)
qb user ban -u USERNAME
qb user unban -u USERNAME
# Promote/Demote user admin privileges
qb user promote -u USERNAME
qb user demote -u USERNAME
# Set user disk quota
qb user quota -u USERNAME -o 500GB
# Change user shell access
qb user shell -u USERNAME -o [full|limited|sudo]Maintenance & Troubleshooting
# Clean system memory caches
qb clean memory
# Clean dashboard logs for a user
qb clean dashboard_logs -u USERNAME
# Remove old system logs (default: 7 days retention)
qb clean system_logs -o 3 -u USERNAME
# Clear software/apt locks
qb clean lock
# Fix user home directory permissions
qb fix home -u USERNAME
# Fix PHP configuration and extensions
qb fix php
# Fix Python configuration
qb fix python
# Reinstall QuickBox to fix version issues
qb fix versionDatabase Management
# Switch to MySQL database
qb manage db -o mysql
# Switch back to SQLite
qb manage db -o sqlite
# Manual database backup
qb manage db -o backup
# Run database maintenance
qb manage db -o maintenance
# Restore from backup (interactive)
qb manage db -o restoreApplication Backup & Recovery
# Backup application config only
qb manage software -o backup -u USERNAME -s sonarr
# Backup application + app binary (for rollbacks)
qb manage software -o backup -o app -u USERNAME -s radarr
# Rollback application to previous version
qb manage software -o rollback -o app -u USERNAME -s overseerr
# Restore application config from backup
qb manage software -o restore -u USERNAME -s bazarr
# Restore default config (from initial install)
qb manage software -o default -u USERNAME -s sabnzbdSystem Configuration
# Set server language
qb manage lang -o [de|dk|en|es|fr|pt|zh-cn]
# Change dashboard access URL/domain
qb manage webroot -o mydomain.com
# Enable/disable public trackers
qb manage trackers -o enable
qb manage trackers -o disable
# Manage API key
qb manage api -k YOUR_API_KEY
qb manage api -o deactivateDatabase Backups
QuickBox automatically backs up your database every 24 hours at 3:30 AM (server time). Backups are stored in /opt/quickbox/backup/system/[DATE_TIME]/db/ and the system retains the 5 most recent backups.
Need Help?
Generate System Logs for Support
Before reaching out for help, generate a system log using qb generate logs. This creates a comprehensive summary of your server’s stats, API activation, and mount information. Access the log via Dashboard → System → Troubleshooting → System Log, or find it at /srv/quickbox/logs/system_log.
Join the Community
Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.