Server Telemetry

QuickBox Pro collects basic system metrics from your server to provide real-time monitoring in your dashboard. This page explains what data is collected, why it’s useful, and how to opt out.

What is Telemetry?

Telemetry is the automatic collection and transmission of system metrics from your QuickBox Pro server to your dashboard. This allows you to monitor your server’s health, resource usage, and user activity from anywhere.

Every 5 minutes, QuickBox Pro sends metrics via the heartbeat system to keep your dashboard up to date.

What Data is Collected

System Metrics

• CPU - Processor name, core count, frequency, and usage percentage
• Memory - Total RAM, used RAM, and free RAM
• Disk Space - Total disk space, used space, and free space
• Network - Interface name, monthly RX/TX totals, and current RX/TX speeds
• Uptime - How long the server has been running
• Load Average - 1-minute, 5-minute, and 15-minute load averages

Server Information

• Hostname - Your server’s hostname
• IP Address - Server’s public IP address
• OS Info - Operating system and version
• Server Version - QuickBox Pro version number

User Activity

• User List - Usernames and email addresses of QuickBox users
• Last Login - When each user last logged in
• Active Status - Whether each user account is active
• Installed Applications - List of installed applications with current and available versions

What is NOT Collected

We do not collect:

• File names, directories, or file contents
• Configuration files or settings
• Passwords or authentication tokens
• Personal media libraries or torrents
• Browsing history or activity logs
• Unique machine IDs or hardware fingerprints
• Your media consumption habits

Why is Telemetry Useful?

Real-time Monitoring - Check your server’s status from your dashboard anytime, anywhere.

Resource Planning - Track CPU, RAM, and disk usage trends over time to plan upgrades.

Update Notifications - See which applications have updates available at a glance.

User Management - Monitor user activity and last login times.

Troubleshooting - Diagnose performance issues remotely without SSH access.

Capacity Planning - Know when to upgrade before running out of resources.

Where to See Your Telemetry

1. Sign in at v3.quickbox.io. The new dashboard is separate from the legacy quickbox.io portal.
2. Open Dashboard → Licenses. The Licenses table lists every key on your account, shows online servers, and has a search bar so you can find a specific hostname fast.
3. Use the actions menu (the ••• button) → “View Telemetry & Details”. This routes you to /dashboard/licenses/<licenseId> where live metrics, API keys, and seat usage for that license live. You can also tap any license card on mobile to reveal the same action.
4. Scroll to “Server Activations”. Each server activation card is collapsible—click it to expand the telemetry drawer, review connection history, and browse per-user update alerts. A refresh icon in the header forces a new heartbeat pull, and the page auto-refreshes every 30 seconds while you keep it open.

Per-server telemetry drawer

When you expand a server under Server Activations you’ll see:

• Status & uptime guardrail – the badge shows Online, Awaiting heartbeat, or Offline, and the uptime counter pauses automatically if the heartbeat stops.
• Live resource tiles – CPU, load averages, RAM, disk, and interface-level RX/TX usage update in-place and will gray out if the server is offline.
• User & app insights – the Active Users grid lists each QuickBox user, their last login, and how many application updates are pending for their installs.
• Connection history controls – tap View History to open a mini log of online/offline spans. You can multi-select entries, clear them, or wipe the full history while the current session stays intact.

API key and account-level telemetry

Below the activations you’ll find Associated API Keys. This section surfaces:

• Status inheritance – if the license is suspended or expired, the badges here instantly flip so you can see why a key stopped working.
• Usage metadata – last used timestamp, originating IP, and total calls for each key, which helps correlate spikes you notice in the server telemetry above.
• Seat add-on context – any extra seat packs purchased for burst workloads appear directly under the keys list so you can match billing events to telemetry increases.

How Does It Work?

1. Cron Job - A cron job runs every 5 minutes (*/5 * * * *)
2. Data Collection - QuickBox Pro gathers system metrics
3. API Request - Data is sent to /api/v1/license/heartbeat via HTTPS
4. Dashboard Display - Metrics appear in your license dashboard in real-time

Security & Privacy

How to Opt Out

To disable telemetry:

qb manage telemetry -o off

To re-enable telemetry:

qb manage telemetry -o on

Technical Implementation

Cron Job

The heartbeat is triggered by a cron job that runs every 5 minutes:

*/5 * * * * root /usr/local/bin/qb manage api -o heartbeat >/dev/null 2>&1

API Endpoint

Data is sent to:

POST /api/v1/license/heartbeat

Request Format

{
  "license_key": "your-license-key",
  "hostname": "server.example.com",
  "os_info": "Ubuntu 22.04 LTS",
  "server_version": "3.0.1",
  "cpu_name": "Intel Xeon E5-2680 v4",
  "cpu_cores": 28,
  "cpu_frequency": "2.40 GHz",
  "cpu_usage": 15.3,
  "memory_total": 67108864,
  "memory_used": 45088768,
  "memory_free": 22020096,
  "disk_total": 1073741824,
  "disk_used": 536870912,
  "disk_free": 536870912,
  "uptime": 1234567,
  "load_average_1": 1.2,
  "load_average_5": 1.5,
  "load_average_15": 1.8,
  "network_interface": "eth0",
  "network_rx_month": 1099511627776,
  "network_tx_month": 549755813888,
  "network_rx_speed": 125000000,
  "network_tx_speed": 125000000,
  "users": [
    {
      "username": "alice",
      "email": "alice@example.com",
      "is_active": true,
      "last_login": "2025-11-23T10:30:00Z",
      "software_updates": {
        "radarr": { "current": "5.14.0.9383", "available": "5.15.1.9428" },
        "sonarr": { "current": "4.0.10.2544", "available": "4.0.11.2680" }
      },
      "software_updates_count": 2
    }
  ]
}

Frequently Asked Questions