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)Recommended
Best experience, current default
Debian 12 (Bookworm)
Stable, long-term choice
Ubuntu 22.04 LTS
Fully supported
Ubuntu 24.04 LTS
Fully supported

End of Life

Debian 11 (Bullseye)EOL June 2026
Debian 10 (Buster)EOL June 2024

Debian 11 has reached end of life and is no longer supported by QuickBox. Upgrade to Debian 12 (Bookworm) to stay on a supported release.

Debian 10 upstream repositories (e.g., php.sury.org) may cause installation failures. QuickBox is not responsible for third-party repository availability.

Recommended Distribution

Tip

We recommend Debian 13 (Trixie) for new installations — it is the current default and offers the best experience. Debian 12 (Bookworm) remains a stable, long-term choice. Learn more about Debian releases at wiki.debian.org/LTS .

Prerequisites

Fresh OS Installation

Ubuntu 22.04/24.04 or Debian 12+ (Debian 13 recommended)

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

Get Your API Key

Fresh Installation Required

Important

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

Warning

Usernames: Avoid usernames that begin or end with numbers, contain uppercase letters, or use reserved names like none, admin, root, user, or username.

Trailing numbers (e.g., john1, media2) create ambiguity with numeric User IDs (UIDs). System tools like chown, scripts, and administration tasks cannot reliably distinguish between a UID and a username that ends in digits — this can cause file ownership errors, broken permissions, and unpredictable behavior across services like systemd, nginx reverse proxies, and applications that derive session or socket names from the username.
Leading numbers (e.g., 1user) are invalid for most Linux user utilities and will fail during account creation.
The none username in particular will fail with applications like rtorrent that use screen, as screen -ls interprets it as “no sessions.”

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:

bash

sudo -i

Why elevate to root?

Important

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:

bash

apt-get install -y sudo

Why is sudo not installed by default?

Note

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:

bash

apt-get -y update && apt-get -y upgrade

Why update?

Note

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:

bash

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:

bash

sudo apt-get install -y curl

What is curl?

Note

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:

bash

./qbpro -u USERNAME -p 'PASSWORD' -k 'API_KEY'

Required Parameters:

Option	Description	Example
`-u`Required	Your desired QuickBox username -u USERNAME	-u USERNAME
`-p`Required	Your desired password. Always wrap it in single quotes so your shell does not interpret symbols, and keep it to letters and numbers for now (see the password note under Prerequisites; you can set a stronger one from the dashboard after installation) -p 'PASSWORD'	-p 'PASSWORD'
`-k`Required	Your unique API Key from your QuickBox account -k 'API_KEY'	-k 'API_KEY'

Get Your API Key

Tip

Your API Key is available in your QuickBox account: quickbox.io/dashboard/api-keys

Advanced Installation Options

Customize your installation with these optional flags:

Option	Description	Example
`-d, --domain`	Domain name for your server (enables automatic SSL) -d 'mydomain.com'	-d 'mydomain.com'
`-e, --email`	Email for notifications and SSL certificate registration -e 'my@email.com'	-e 'my@email.com'
`-dns, --dns`	Opt-in DNS-01 challenge flow for wildcard/advanced SSL -dns	-dns
`--dns-provider`	Pre-select DNS provider for automated challenges --dns-provider cloudflare	--dns-provider cloudflare
`--dns-credentials`	Path to a KEY=VALUE credential file (non-interactive) --dns-credentials /root/dns.env	--dns-credentials /root/dns.env
`-ftp, --ftp`	Custom FTP port for enhanced security -ftp 5757	-ftp 5757
`-ssh, --ssh-port`	Custom SSH port (security best practice) -ssh 4747	-ssh 4747
`-t, --trackers`	Tracker control: 'allowed' or 'blocked' -t blocked	-t blocked

Advanced Installation Example

bash

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

Warning

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.

bash

./qbpro -u USERNAME -p 'PASSWORD' -k 'API_KEY' -d 'media.example.com' -dns

bash

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

Note

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

bash

./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:

bash

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 /root directory
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 65+ applications and install with one click

Explore the Dashboard

Tip

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

Browse Applications

65+ pre-configured applications ready to install

CLI Reference

Master the powerful qb command-line tool

Troubleshooting Guide

Common issues and solutions

Join Discord

Get help from the community

Installation Complete!

Congratulations! QuickBox Pro is now installed. Log in to the dashboard at https://your-server-ip (or your domain) and open App Dashboard → Package Management to install your first applications — browse the catalog, click Install, and watch the log stream live. The dashboard is the recommended surface for installing and managing apps; see App Management for the full walkthrough.

The CLI essentials below cover the same ground for power users and automation:

qb -h

View the complete help manual with all available commands and options

qb install [app]

Install any of 65+ 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

bash

# 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]

Tip

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

bash

# 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

bash

# Clean system memory caches
qb clean memory
 
# 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
 
# Repair the PHP-FPM pool of each PHP application
qb fix php
 
# Update the PHP of each PHP application to its security fixes
qb fix php --security
 
# Fix Python configuration
qb fix python
 
# Reinstall QuickBox to fix version issues
qb fix version

Database Management

bash

# 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

bash

# 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 seerr
 
# 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

bash

# 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

Note

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

Tip

Before reaching out for help, generate a system log using qb generate log. 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 /opt/quickbox/logs/system_log.

Troubleshooting Guide

Common issues and solutions

GitHub Issues

Report bugs or request features

Application Docs

Detailed guides for each application

CLI Reference

Complete command-line reference

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