Skip to content

Setup Wizards

tunlx ships three wizards that get you from zero to a working setup without hand-editing JSON.

Dashboard onboarding A first-login wizard that helps you set credentials, choose inbound/outbound modes, and create your first proxy. Triggered automatically when setup.dashboardWizardCompleted is false.

Regional IPTV wizard Builds a ready-to-watch country lineup from iptv-org in viewer-expected order — UK gets Freeview-style ordering — with EPG ids wired, streams verified on creation, and optional self-healing. Launched from the Add Proxy chooser in both Simple and Advanced mode.

Xtream CLI wizard A terminal walkthrough that builds an Xtream service from the iptv-org catalog with demo users. Launch with ./tunlx --xtremeWizard.

Dashboard onboarding

When tunlx starts for the first time (no credentials set, or setup.dashboardWizardCompleted is false), the dashboard returns a wizard payload instead of the regular login flow.

Login

The wizard walks you through:

  1. Admin credentials. Pick a username and a strong password — tunlx hashes it with bcrypt before saving.
  2. Inbound mode. Public, Tailnet-only, or both. The Tailnet option enables the embedded tsnet node and prompts for an auth key.
  3. Outbound mode. System routing, WireGuard, or a Tailscale exit node. If you pick vpn, you can paste a WireGuard config or set up Mullvad on the spot.
  4. First proxy. Optional. Add a Standard proxy with target, host/port, credentials, and route.
  5. Finish. tunlx writes config.json and marks setup.dashboardWizardCompleted: true.

You can replay onboarding any time by setting that flag back to false and reloading the dashboard.

Regional IPTV wizard

Open Add Proxy → Regional IPTV wizard in the dashboard to build a country lineup that looks the way viewers expect, in four steps:

  1. Region. Pick a country from the live iptv-org catalog. Regions with a curated ordering preset (UK, US today) are flagged — the UK preset opens with BBC One, BBC Two, ITV1, Channel 4, Channel 5, then the rest of the Freeview-style lineup. Every other country gets themed category groups (Entertainment, News, Sports, Kids, …) sorted alphabetically.
  2. Preview. See the exact groups and channel order before anything is saved, including which featured channels currently have no streams.
  3. Access & healing. Create the first viewer login and switch self-healing on (default: every 6 hours). EPG is automatic: the wizard selects a recommended public XMLTV guide for the chosen country; paste your own URL only if you want to override it.
  4. Done. The service starts immediately — no restart of anything else — and the wizard hands you the M3U, player API, and XMLTV URLs to paste into a player. A verification pass starts automatically in the background: every channel is probed, dead primaries are swapped for working backups, and channels with no working stream at all are disabled so they never reach a player. The done step follows the pass live, and you can re-run it any time with the health-check button.

The wizard is available from the Add Proxy chooser in both Simple and Advanced dashboard modes. Channels whose every published stream needs a special User-Agent or Referrer to play are excluded up front — they cannot be relayed reliably through the service.

Every channel the wizard creates remembers its iptv-org identity (iptvOrgChannelId) and up to five ranked alternate streams (backupStreamUrls), which is what makes self-healing possible later: channel numbering stays stable while dead URLs are swapped out underneath.

Channel ids are assigned 1..N in display order and epgChannelId is set to the canonical iptv-org id (e.g. BBCOne.uk), so M3U tvg-ids, the service's own xmltv.php, and any iptv-org-convention guide all agree.

Xtream CLI wizard

The CLI wizard is the fastest path to a fully populated panel.

./tunlx --xtremeWizard

It prompts you through:

  1. Service name, host, port. What clients will connect to.
  2. Country and category picker. Filter the iptv-org catalog interactively.
  3. Limit and NSFW toggle. Cap each generated group at a sensible size.
  4. Demo users. Generates one or more Xtream users with bcrypt-hashed passwords.
  5. Stream sampling (optional). Probe a handful of imported channels before committing, so you know the upstreams are alive.
  6. Write back. Saves to config.json. If a service with the same name exists, the wizard asks before replacing it.

Wizard

Sample wizard pass

$ ./tunlx --xtremeWizard

Welcome to the tunlx Xtream wizard.

  1. Service name  : panel
  2. Listen host   : 0.0.0.0
  3. Listen port   : 20000

Build a group from iptv-org? [Y/n] y
  Group name       : World News
  Countries        : us, gb, de
  Categories       : news
  Limit            : 50
  Include NSFW?    : no

Sample 8 channels to check reachability? [Y/n] y
  Probing... 7/8 ok, 1 dropped.

Add user? [Y/n] y
  Username         : alice
  Password         : ********
  Expiry (YYYY-MM-DD or blank): 2026-12-31
  Max connections  : 2

Write to /app/data/config.json? [Y/n] y
✔ Xtream service "panel" saved.

When to use which

Use the CLI wizard when… Use the dashboard when…
Bringing up a brand-new host headless Editing an existing service
Scripting a fresh deploy with predictable inputs Reviewing what's already configured
You want a quick demo lineup in 60 seconds You need to manage users, EPG, or category labels