Skip to Content
DocsGetting Started with QuickBox Pro

Getting Started with QuickBox Pro

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 -i

Why 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 sudo

Why 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 upgrade

Why 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 qbpro

If curl is not found:

Install curl with the following command:

sudo apt-get install -y curl

What 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, --domain

Domain name for your server (enables automatic SSL)

-d 'mydomain.com'
-e, --email

Email for notifications and SSL certificate registration

-e 'my@email.com'
-dns, --dns

Opt-in DNS-01 challenge flow for wildcard/advanced SSL

-dns
--dns-provider

Pre-select DNS provider for automated challenges

--dns-provider cloudflare
--dns-credentials

Path to a KEY=VALUE credential file (non-interactive)

--dns-credentials /root/dns.env
-ftp, --ftp

Custom FTP port for enhanced security

-ftp 5757
-ssh, --ssh-port

Custom SSH port (security best practice)

-ssh 4747
-t, --trackers

Tracker control: 'allowed' or 'blocked'

-t blocked

Advanced Installation Example

./qbpro -u USERNAME -p 'PASSWORD' -k 'API_KEY' -d 'mydomain.com' -e 'my@email.com' -ftp 5757 -ssh 4747 -t blocked

This 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 required KEY=VALUE pairs. Credentials are stored securely via qb 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 (one KEY=VALUE per 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:

  1. Changes to the /root directory
  2. Updates system packages
  3. Installs curl if not present
  4. Downloads the QuickBox Pro installer
  5. 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 quickbox

Pro 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 en

Advanced 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 version

Database 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 restore

Application 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 sabnzbd

System 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 deactivate

Database 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.

Dedicated Support
Feature Previews
Community Configs
Active Discussions
Join Discord Server