Dashboard Tour¶
A visual reference for every screen in the tunlx dashboard. If you are looking for "what does that dialog do?", it is on this page.
All screenshots are from a live instance running two standard proxies, one composite catalog and one Xtream service. Addresses shown are RFC 5737 documentation values.
Signing in¶
Session cookies are signed with sessionSecret. The login endpoint is rate
limited hard on purpose — roughly one attempt every two seconds — so
brute-forcing the dashboard is not practical. Repeated failures simply queue.
The overview¶
The page leads with what you came to do:
- Counts — how many proxies are Streaming Now (they carried traffic in the last 15 seconds), how many are Ready (listening, waiting for a player), the traffic through them right now, and the total. A proxy whose listener did not start is neither; the Ready tile says so and its card shows the reason.
- Proxies — the list, with Add Proxy beside its heading. It has filter tabs (All / Streaming / Ready / MediaFlow) and a search box bound to the / key. With nothing configured the counts, the tabs and the search box are left out (four zeros and a search over nothing say nothing), and the page offers two ways in as its first content: Add Your First Proxy for a provider you already have, and Try it with free channels, which opens the Regional IPTV Wizard. The Open player menu offers the same first step.
- This server — CPU, memory and outbound network for the machine tunlx is running on, folded under the list. Its summary line already says the three numbers, with a dot for how the host is doing and the words "Heavy load" or "Critical" when it is not well; open it for the three tiles. It stays open or closed as you leave it. A tile shows a dash until the host has answered and the line says "Host metrics unavailable" when it stops answering; a pill appears only while the value is moving.
The list is drawn again only when something in it changed, and not while you have text selected in it, so a server URL you are copying stays selected.
Simple and Advanced modes¶
Simple mode drops the composite cards, Xtream service editing, the config editor, import/export and the MediaFlow filter, while keeping Standard proxies, Xtream service cards, and the Regional IPTV Wizard. It is the right default for a host that runs a couple of standard proxies. Everything hidden is still configured and still running — only the controls are hidden. The list counts what it hides, and a control that needs Advanced mode offers a Switch to Advanced button. See Dashboard Modes.
Dark mode¶
The theme toggle lives in the navbar and persists per browser.
Expanded proxy cards¶
Cards expand independently. Each type exposes a different action set — a composite proxy has Categories but no upstream account, an Xtream service has Categories and Users but no target server.
Host, target, egress route, EPG state, per-proxy logging, the collapsible upstream account and connection panels, and live bandwidth and RPS.
Category and channel counts, active viewers, a content-type summary, and the Categories and Users managers in place of an upstream account.
Creating and editing proxies¶
Choosing a type¶
Add Proxy always starts here. See Step 3 of Getting Started for how to choose.
Standard proxy¶
Target server, bind host and port, upstream Xtream credentials, egress route, MediaFlow, EPG schedule and the anti-block options. The Auto-fill button parses a pasted M3U URL and fills the fields it can infer.
Composite proxy¶
A composite proxy has no target of its own — it borrows categories from proxies
you already have, behind one set of client credentials. categoryPrefix labels
merged categories so viewers can tell sources apart.
Xtream service¶
Identity, bind port, and delivery options — including Remux HLS streams to
MPEG-TS, which uses ffmpeg to copy (not re-encode) .m3u8 sources into
transport-stream segments for legacy devices.
When it is ready¶
Saving a new proxy, composite proxy or Xtream service (or a clone of one)
waits until its listener is up, then opens a dialog with what a player needs:
the server address, the login and the playlist link with copy buttons (the
password is drawn as dots; its button copies the real one), an Open in web
player button, and for a composite proxy or a service the next step —
Choose categories or Add viewers. A page opened at a name or address
other than localhost also gets the same address on this page's host, for
devices on the same network. A listener that cannot bind keeps its error
toast, and saving an edit keeps its toast.
Managing content¶
Categories¶
Categories are split by content type — Live, Movies, Series — each with its own count. The overflow menu on each tab offers Import M3U, Import from iptv-org and a bulk delete.
Category and channel IDs must be numeric
The Xtream Codes API represents category_id and stream_id as numbers.
tunlx assigns numeric IDs automatically when you create things through the
dashboard, but if you hand-edit config.json and give a group an ID like
grp-news, that group is silently skipped from the API — clients see an
empty category list while the dashboard still shows it. A warning is logged.
Stick to numeric IDs when editing JSON directly.
Channels¶
Per-channel: enable toggle, edit, delete, and a drag handle that sets the order players see. The All / Enabled / Disabled filter carries live counts. Reordering is disabled while a filter is active, since a partial list cannot express a full ordering.
Viewers¶
Each viewer of an Xtream service gets their own login, expiry date and connection limit. Passwords are bcrypt-hashed. Deactivating a viewer keeps the record but refuses their logins.
Composite category selection¶
Pick which categories from which source proxies make up the merged catalog.
Importing channels¶
From iptv-org¶
Search the public iptv-org catalog by name, country and category, then import a selection straight into one of your categories. The catalog is cached in memory with a visible refresh timestamp.
From an M3U playlist¶
Paste a URL or upload a file. tunlx parses #EXTINF metadata — channel name,
logo, tvg-id and group — and maps it onto its own channel model.
Networking¶
Inbound and outbound¶
Sets both directions globally, with the current WireGuard and Tailscale status
shown inline. Per-proxy route overrides the outbound choice.
WireGuard¶
Two modes. Manual takes a WireGuard config you paste or point at on disk. Provider mode drives Mullvad directly: tunlx fetches the server list, keeps it refreshed on a schedule, and can filter by country, city or hostname. See WireGuard / VPN.
Tailscale¶
tunlx embeds a tsnet node, so it joins your tailnet as its own device without
needing Tailscale installed on the host. It can also select an exit node for
outbound traffic. See Tailscale Access.
Operations¶
Stream health tests¶
Probes channels asynchronously across HLS, MPEG-TS, MP4 and Matroska.
These are shallow probes
A test fetches metadata from the head of the stream (up to 512 KB). It proves the upstream answers and looks like the media it claims to be. It does not walk every segment, so a pass is not a guarantee that the whole stream is intact. See Stream Health Tests.
Activity and telemetry¶
Request-by-request activity per proxy and per viewer, filterable and
exportable to CSV. Which actions get recorded is governed by
userActivityPolicies, so you can log stream starts without logging every
guide poll. See Activity & Telemetry.
The OpenAPI explorer¶
Every proxy publishes a Swagger UI describing its own Xtream endpoints, with that proxy's real base URL already filled in — useful for checking exactly what a client will receive. See the Xtream API reference.
Configuration¶
The config editor¶
Advanced mode only. Edits config.json in place, with Validate JSON to
check before saving. Passwords, tokens and keys show as tunlx-secret.v1.…
codes: leave one as it is to keep its value, or replace it with the new value
to change it.
Viewing the effective config¶
A read-only view of the running configuration, handy for support. Passwords,
tokens and keys, and the password inside a stream address
(/live/<user>/<password>/<id>.ts), are shown as dots, so what Copy JSON
copies is safe to paste into a bug report. Tick Show secrets to see them
(for copying a proxy definition between hosts, say); the switch is off every
time the dialog opens. View JSON in a proxy's, composite's or Xtream
service's editor works the same way, and so do the stream addresses in the
Channels dialog.
The page never holds them either. The server sends a code in place of each one (see Secrets in the answers), and the page asks for the real value only when you ask for it: Show secrets, a copy button, the eye beside a password, Test on a channel, or Show keys in the WireGuard dialog.
Secrets are encrypted at rest
sessionSecret and other sensitive fields are AES-256 encrypted in
config.json with the enc:v1: prefix, using a key auto-generated at
config.key in the same directory as the config file. Back up
config.key alongside config.json and never commit either — a config
without its key cannot be decrypted.
Wizards¶
The setup wizard is reachable any time from the navbar, not just on first run. It links out to the WireGuard, Tailscale and routing dialogs, and can hand off to the service builder.
The TV-helper flow builds a working Xtream service from the iptv-org catalog — pick a country and some categories and it creates the categories, channels and a demo viewer for you. Full walkthrough in Setup Wizards.
On a phone¶
The dashboard works from a phone, and everything you tap is made for a thumb: on a touch screen or a narrow window every button, field, tab, menu row and checkbox row is at least 44 px tall, and the smallest text anywhere is 12 px. Dialogs scroll inside themselves, so their buttons stay on the screen however long the form is, and they lose the Maximize button, which has nothing to do on a screen that is already full. Cards are reordered by dragging the handle at their left edge, which a phone does not show; do that from a computer.
The web player¶
Browse by content type and category, then play in the browser. It is the fastest way to answer "is this a tunlx problem or a client problem?" — if a stream plays here, tunlx is serving it correctly.
Xtream services prompt for one of their viewer logins first; standard and composite proxies open straight into the browser. The full walkthrough — entry points, playback controls, EPG timeline, mobile layout — is in Web Player.