IPTVBoss

IPTV playlist and EPG management with a headless XC Server

IPTVBoss manages IPTV playlists and EPG data and re-serves them through a headless Xtream Codes (XC) server. QuickBox Pro installs it as a single server-level application owned by the installing admin: one always-on XC Server (loopback-bound, reverse-proxied by nginx with per-subdomain SSL) that keeps your playlists and EPG in sync internally, on a schedule you set in IPTVBoss’s own settings - in the desktop editor (the path if you have no domain and SSL) or the Server Console once a subdomain is attached. The IPTVBoss license is user-owned - QuickBox never accepts, stores, logs, or automates any license key; you activate IPTVBoss through its own interface.

When to use it

Installation

Server-level install requires an admin

IPTVBoss is a single server-level application, so only a QuickBox admin (account level 9 or higher) can install it, and there is one install per server. The -u <adminuser> you pass records the install against that admin and homes IPTVBoss’s config and data under /home/<adminuser>/IPTVBoss. The service runs as that admin.

QuickBox installs IPTVBoss from its beta build. The beta is the only supported build: it carries the headless XC Server mode that QuickBox’s managed service depends on, which the stable build does not expose. There is therefore no stable/beta channel selector and no --beta flag for IPTVBoss - the beta build is always used.

Install from the Dashboard

Open App Dashboard -> Package Management (/dashboard?mode=packages), find IPTVBoss under the Media Servers category, and click Install. The dashboard streams the install log live and IPTVBoss appears on your App Dashboard when it finishes. Reinstall, Update, and Remove are available from the same catalog.

In the install dialog you can switch the domain toggle to Custom and enter a subdomain - the install then issues SSL and serves the XC Server endpoint on that subdomain (see The XC Server endpoint and SSL subdomain). Because IPTVBoss is server-level, install it from an admin account.

Install and manage from the CLI

The CLI runs the same install pipeline and is suited to automation and scripting. The -d domain and the DNS flags map to the dashboard choices above:

qb install iptvboss -u adminuser
qb install iptvboss -u adminuser -d iptvboss.example.com
qb install iptvboss -u adminuser -d iptvboss.example.com --dns --dns-provider cloudflare
qb reinstall iptvboss -u adminuser
qb update iptvboss -u adminuser
qb remove iptvboss -u adminuser
qb help iptvboss

Passing -d <domain> issues the Let’s Encrypt certificate and writes the subdomain nginx vhost as part of the install. Add --dns --dns-provider <provider> for a DNS-01 challenge (needed for wildcard certificates). Full flag reference: CLI Reference.

Architecture

QuickBox runs IPTVBoss as a single always-on service, iptvboss-xcserver.service - a long-running unit (Restart=always) bound to 127.0.0.1:<port> and reverse-proxied by nginx. This is the XC Server that serves your Xtream Codes API and portal, and it is the primary status and control target on the App Dashboard row.

The same service keeps your lineup current internally: it fetches your sources, refreshes EPG and playlists, and writes backups on a schedule you set in IPTVBoss’s own settings - in the desktop editor or the Server Console once a subdomain is attached. There is no separate processing unit or timer to manage from QuickBox, and nothing to keep open on the desktop - see Keeping playlists and EPG in sync.

The XC Server endpoint and SSL subdomain

The SSL subdomain is the XC Server endpoint - the address your IPTV clients and players connect to for the Xtream Codes service, and it is also where the XC Server serves its own browser-based Server Console. It is not a management page for the IPTVBoss app; you configure IPTVBoss in its desktop editor (see Licensing and the IPTVBoss editor).

Because the XC Server is root-path oriented, that endpoint is served at the root of a dedicated subdomain - for example https://iptvboss.example.com/ - not on a subpath. Attach a subdomain and QuickBox reverse-proxies the loopback XC port to it over HTTPS.

There are three ways to attach the subdomain: a single-call install (Path A), a post-install retrofit from the CLI (Path B), and the dashboard SSL Control page (Path C).

Path A - Subdomain at install time

Point a DNS record (A or CNAME) for your chosen subdomain at the server, then pass -d <domain> to the install:

qb install iptvboss -u adminuser -d iptvboss.example.com

The install issues the certificate, writes the subdomain vhost, and starts the XC Server behind it in one call - no separate lecert step required.

Path B - Retrofit a subdomain to an existing install

If IPTVBoss is already installed and you want to attach (or move) its subdomain, issue the certificate with the IPTVBoss lecert flag. The -u is required - it names the admin that owns the install:

qb install lecert --iptvboss -d iptvboss.example.com -u adminuser

This requests a Let’s Encrypt certificate (HTTP-01 challenge by default), writes the per-user subdomain vhost iptvboss.example.com reverse-proxied to the assigned XC port, reloads nginx, and registers the certificate for automatic renewal.

Wildcard or DNS challenge: add --dns --dns-provider cloudflare (or another supported provider) and use a wildcard domain such as *.example.com. See the Let’s Encrypt application reference for the full list of supported DNS providers.

Path C - Dashboard SSL Control

The dashboard’s SSL Control page at System -> SSL Control (/system/ssl) exposes the same flow. Pick IPTVBoss as the target, enter the subdomain and the owning admin username, choose the challenge method, and QuickBox runs the same qb install lecert --iptvboss pipeline under the hood. For end-to-end setup, supported DNS providers, wildcard certificates, and renewal behavior, see the SSL Certificates dashboard page.

The Server Console

The XC Server serves its own browser-based Server Console - IPTVBoss’s admin interface for the running Xtream Codes server. Reach it by appending /boss.php to your SSL subdomain, for example https://iptvboss.example.com/boss.php.

The root of the subdomain is not the console - it is the Xtream Codes client endpoint your IPTV players connect to, and it returns a 404 in a browser because it is not a page. The Server Console lives only at /boss.php.

The Server Console administers the running XC Server, and only that:

• XC Server users and paired devices
• Server settings, including the internal sync schedule for your playlists and EPG
• Server logs and API keys
• Console security, including two-factor authentication

It does not edit your layouts, playlists, EPG, or sources - that is the job of the IPTVBoss desktop editor reached over a desktop remote (see Licensing and the IPTVBoss editor). Keep the two distinct: the desktop editor curates your lineup; the Server Console administers the XC Server that re-serves it.

The Server Console is the web mirror of IPTVBoss’s settings for installs that have attached an SSL subdomain - so it is one way to reach the internal sync schedule, not the only one. If you run IPTVBoss from the desktop GUI without a domain and SSL, set the same sync schedule in the desktop editor instead; both write the same IPTVBoss setting.

The Server Console has its own admin account

The Server Console signs in with its own administrator account - it is not your QuickBox login, and QuickBox credentials will not get you in. On the first XC Server start a default admin account can be created automatically, in which case the console shows a login screen rather than a first-run setup form.

If you are locked out of an auto-generated admin account, reset the console administrator on the server. Stop the XC Server first so its data is unlocked, run the reset against the install’s data directory, then start the service again:

systemctl stop iptvboss-xcserver.service
iptvboss -xcserver -xc-reset-admin -directory /home/adminuser/IPTVBoss
systemctl start iptvboss-xcserver.service

The reset is interactive - it asks you to confirm and refuses a piped answer, so run it from an interactive shell. It clears only the console’s administrator identity, its two-factor setup, and trusted sessions; it preserves every XC Server user, along with your sources, layouts, settings, and backups. The next time the XC Server starts, the console shows a Create administrator form so you can set your own credentials.

Open the Server Console from the dashboard

Once an SSL subdomain is attached, the launch icon on the IPTVBoss row of the App Dashboard (/dashboard, the default control view) opens the Server Console at <subdomain>/boss.php directly. Until a subdomain is attached the XC Server has no public endpoint, so the row stays launchless - attach one first (see The XC Server endpoint and SSL subdomain).

Managing IPTVBoss from the dashboard

Open the App Dashboard (/dashboard, the default control view), find the IPTVBoss row, and expand it. The row itself shows the XC Server status, version, and assigned port and carries the start, stop, and restart controls. Its expansion has two tabs:

XC Server is the control tab. Across the top it gathers the XC-specific controls:

• Apply / Reload the always-on service after a change you made in the desktop editor or Server Console.
• The XC endpoint and SSL status, with a link to manage the certificate.
• Desktop-access options for reaching the IPTVBoss editor.

Below those it shows the same baseline sections every app row has - Service & Access (the URL), Paths (the data directory, the log directory, and the nginx config), Operations (Logs, Open, Edit Nginx, and Backup and Restore), and Links (the IPTVBoss website, its guide, and these docs). There is no API and Secrets section, because IPTVBoss exposes no usable API. See Backing up IPTVBoss for what Backup and Restore cover.

Recent Sync is a read-only view of the internal sync: how long ago the last sync ran and when the next one is due, a summary of what synced, and the full service log (live or history) one toggle away. It reports on the sync - it does not set the schedule.

The sync schedule itself lives in IPTVBoss’s own settings - the desktop editor, or the Server Console once a subdomain is attached - not the dashboard. Because IPTVBoss is server-level infrastructure, the row and its panel are shown to admins only. Any admin can manage the install regardless of which admin ran it.

Licensing and the IPTVBoss editor

IPTVBoss’s license is user-owned. QuickBox never accepts, stores, logs, or automates any license key - activation and full configuration happen in IPTVBoss’s own editor, which is a graphical desktop application.

To reach the editor on a headless server you need a desktop remote installed for the admin account - either noVNC (in-browser) or x2go (native client). Install one of those, open a desktop session, launch IPTVBoss, and complete licensing and any source configuration there. Once a remote is installed, the IPTVBoss row’s Desktop Access gives you Open in Browser (noVNC) and Open with X2Go so you can start a desktop session straight from the dashboard.

Keeping playlists and EPG in sync

The always-on XC Server keeps your lineup current on its own: it fetches your sources, refreshes EPG and playlists, and writes backups internally, with no separate processing run to schedule from QuickBox and no desktop app to leave open.

Set how often it syncs in IPTVBoss’s own settings. The universal path every install has is the desktop editor - open a desktop session over noVNC or x2go, launch IPTVBoss, and adjust the sync schedule there. If you have attached an SSL subdomain, the Server Console mirrors the same setting: open it at /boss.php on your subdomain (see The Server Console) and adjust the sync schedule under Server Settings. Both write the same IPTVBoss setting, and the schedule lives with the XC Server itself, so it keeps running whether or not anyone is signed in to the dashboard.

Live TV guide in the Media Portal

Once IPTVBoss is installed and you enable an XMLTV output in its editor, QuickBox reads that export to power a Now / Next / Upcoming TV guide on Live TV channel pages in the dashboard’s Media Portal. The guide works for Emby, Jellyfin, and Plex channels alike, and it turns on by itself - there is nothing to wire up beyond enabling the export.

What you enable in IPTVBoss: open the desktop editor (over noVNC or x2go) and turn on an XMLTV output in its output settings. A fresh install ships with no output configured, so until you enable one the channel pages read No guide yet.

What it unlocks: each Live TV channel page then shows the current programme with a progress bar, the programme that follows, and up to six upcoming programmes, with times, categories, and New / Live flags. Viewers reach a channel page by clicking a Live TV session’s title in the Streaming Dashboard. The same export also powers the full-lineup TV Guide page in the Control Center - every channel as a row on a channel-by-time grid. IPTVBoss is not the only source: a Dispatcharr install feeds the same guide automatically, and if you run both their channels merge into one grid.

Provider data: the TV Guide page can also filter the grid by IPTV provider and label live streams by source. That filter appears once IPTVBoss is saving local database backups, because that is where QuickBox learns which provider each channel comes from - the XMLTV export alone does not carry it. The rest of the guide works without backups.

An admin toggle, Show guide in Media Portal (on by default), and the live export status (channel and programme counts, last update) live on the IPTVBoss Live TV Guide card in Streaming Settings. QuickBox only reads the export - it never changes your IPTVBoss output or lineup.

VPN routing

IPTVBoss can route all of its upstream traffic through a VPN tunnel using QuickBox Pro’s app-scoped routing, with either a WireGuard or an OpenVPN backend. When routing is enabled, the XC Server’s playlist and EPG source fetches and every other upstream call exit through the VPN peer. Your IPTV clients connecting to the XC Server subdomain are unaffected, and the SSL subdomain and dashboard proxy keep working because QuickBox routes that traffic to the loopback-bound XC Server inside the namespace automatically.

IPTVBoss is a single system-wide service (iptvboss-xcserver) owned by the installing admin, so only one routing profile can be active for it at a time, the same as Plex. It appears in the App-Scoped Routing card once IPTVBoss is installed and its service is running; there is no pre-install staging.

How to enable VPN routing for IPTVBoss:

1. Go to System > VPN Control (/system/vpn) in the dashboard
2. Upload at least one WireGuard .conf or OpenVPN .ovpn file if you have not done so already
3. Scroll to the App-Scoped Routing card on the VPN Control page
4. Select IPTVBoss from the app list
5. Choose the tunnel backend and a peer configuration from the dropdown
6. Click Enable Routing

The XC Server restarts inside its VPN network namespace (qb_iptvboss). Your playlist and EPG providers will see the VPN exit IP from that point forward.

The default kill-switch stale threshold for IPTVBoss is 30 minutes, matching Dispatcharr and qBittorrent. IPTVBoss keeps long-lived sync sessions and recurring EPG fetches, so a shorter window risks tearing down routing during legitimate gaps in upstream activity. You can adjust it on the app row inside the App-Scoped Routing card.

For full details on routing configuration, kill switch settings, and live metrics, see the VPN Control dashboard page.

Configuration and files

Backing up IPTVBoss

IPTVBoss holds state that is slow to recreate by hand - your layouts, sources, XC Server configuration, EPG, XC Server users, and its own internal backups/ - all under the installing admin’s home directory. Expand the IPTVBoss row on the App Dashboard (/dashboard, the default control view) and use the XC Server tab’s Operations to protect it:

• Backup offers a Full backup of the IPTVBoss install and an Nginx backup of just the reverse-proxy config. There is no Config Only option, because IPTVBoss keeps its settings in the binary H2 database rather than an editable text file.
• Restore brings back a Full or Nginx backup you took earlier.

Backup and Restore are control actions on the App Dashboard, not the Package Management catalog. They are admin-only, matching the server-level nature of the app.

Service management

The IPTVBoss service is static (not per-user templated). Manage it by name:

# Always-on XC Server
systemctl status iptvboss-xcserver.service
systemctl restart iptvboss-xcserver.service
journalctl -u iptvboss-xcserver.service -f

Updating IPTVBoss

IPTVBoss updates through its vendor apt source, which the install registers. Run:

qb update iptvboss -u adminuser

This upgrades the IPTVBoss package to the latest beta build, refreshes the dependency bridge, and leaves your config, data, and schedule in place. When an update is available, the IPTVBoss row on the App Dashboard shows an update pill you can act on directly.

Delete Protection

The always-on XC Server (iptvboss-xcserver.service) is a first-class Delete Protection target, so IPTVBoss is covered the moment you enable the feature. Delete Protection guards against a runaway deletion during a sync by slowing large unlink operations.

Enable it from Settings > General > Feature Flags in the dashboard. Delete Protection is opt-in and honors your setting - it does nothing until an admin turns it on, and it then applies to IPTVBoss automatically. For per-app thresholds and the full behavior, see the Delete Protection page.

Troubleshooting

The XC Server will not start

The subdomain is not reachable

Confirm the DNS record for your subdomain points at the server, that the certificate issued (re-run the lecert step in The XC Server endpoint and SSL subdomain if it did not), and that the XC Server is running. Until a subdomain is attached the XC Server has no public endpoint - configure IPTVBoss in its desktop editor and control the service from the App Dashboard in the meantime.

Playlists or EPG look stale

The XC Server syncs internally on the schedule set in IPTVBoss’s own settings, so a stale lineup usually means the schedule is off or too infrequent, a source failed, or the server has not reloaded after an edit.

# Confirm the XC Server is running and read its recent log
systemctl status iptvboss-xcserver.service
journalctl -u iptvboss-xcserver.service -n 100

Check the sync schedule in IPTVBoss’s settings - in the desktop editor over a desktop remote, or, if you have a subdomain, in the Server Console at /boss.php under Server Settings (where you can also read the server logs). If you just changed your lineup in the desktop editor, use Apply / Reload on the XC Server panel so the server serves the updated output.

I cannot license or configure IPTVBoss

Licensing and source configuration happen in IPTVBoss’s own graphical editor, which needs a desktop remote. Install noVNC or x2go for the admin account, open a desktop session, and launch IPTVBoss from there.

Best practices

Frequently asked questions

Related applications

Resources