Getting Started¶
This is the end-to-end path: from a freshly installed tunlx to a client app playing a stream. Every step below is shown with the screen you will actually see.
If you have not installed tunlx yet, start with Installation and come back here.
Prefer to be guided?
On a brand-new install the dashboard offers an onboarding wizard the first
time you sign in, and there is a terminal wizard (./tunlx --xtremeWizard)
that builds a whole channel lineup for you. Both are covered in
Setup Wizards. This page is the manual path, so you can
see what each piece does.
Step 1 — Sign in¶
tunlx serves its dashboard on port 6060 by default. Open
http://<host-ip>:6060 and you land on the sign-in screen.
On a first run with no config.json, tunlx generates one and prints a random
admin password to the console. Look for this block in the startup output (or in
docker compose logs tunlx):
================================================================
CRITICAL: No configuration file found. Generating default config.
Your default admin password is: xXxXxXxXxXxX
Please log in and change this password immediately.
================================================================
The username is admin. Change the password as soon as you are in — the
dashboard has a Update Credentials dialog for exactly this, and the new
password is stored bcrypt-hashed.
Step 2 — Find your way around¶
After signing in you get the operations dashboard: system health at the top, then every proxy you have configured as a card.
Simple mode vs Advanced mode¶
The dashboard opens in Simple mode, which hides the machinery you do not need on day one. The toggle in the navbar switches to Advanced mode, which adds composite proxies, Xtream services, the config editor, import/export, and the extra filter tabs.
You need Advanced mode for most of this guide, so switch it on now. See Dashboard Modes for exactly what each mode reveals.
The navbar is the control surface
The icons on the right of the navbar are how you reach everything that is not a proxy: the setup wizard, the web player, Networking, the config editor, stream health tests, activity and telemetry, and the UI-mode toggle. The two chips on the left show your current inbound and outbound routing at a glance.
Step 3 — Choose what you are building¶
Click Add Proxy and tunlx asks which of the three shapes you want. This is the most important decision in the whole product, so it is worth understanding before you click.
flowchart TD
A[What do you have?] --> B{One upstream<br/>Xtream provider?}
B -->|Yes| C{Want to change<br/>what it offers?}
C -->|No, just front it| D[Standard Proxy]
C -->|Merge or curate it| E[Composite Proxy]
B -->|No, I have raw<br/>stream URLs| F[Xtream Service]
D --> D1[Stable URL for a provider line<br/>Per-proxy egress routing<br/>EPG auto-refresh]
E --> E1[Pick categories from several proxies<br/>One set of credentials for clients]
F --> F1[You own categories, channels and viewers<br/>Full Xtream Codes API, no upstream panel]| Blueprint | Use it when | Guide |
|---|---|---|
| Standard Proxy | You have a provider line and want a stable endpoint in front of it, with your own routing and EPG schedule. | Standard Proxies |
| Composite Proxy | You have two or more proxies and want to publish one merged catalog under a single login. | Composite Catalogs |
| Xtream Service | You have stream URLs (or want to pull from iptv-org) and want tunlx itself to be the panel. | Xtream Services |
The rest of this guide walks the Standard Proxy path, because it is the shortest route to working playback. Steps 6 and 7 show where the other two diverge.
Step 4 — Create a Standard proxy¶
Choosing Configure Standard Proxy opens the proxy form.
Fill in the four fields that matter, and leave everything else alone for now:
- Name — how the proxy appears on the dashboard and in URLs. Letters and numbers, no spaces.
- Target server — your upstream, including scheme and port:
http://line.example.com:8080. - Bind host and port — where this proxy listens. Use the host's LAN or public IP and a free port such as
9101. - Xtream username and password — the credentials your provider issued. tunlx uses these upstream; your clients never see them.
Keep the first proxy boring
Do not switch on MediaFlow, VPN routing, or EPG auto-refresh yet. Get plain playback working first, then add one feature at a time. If you enable three things at once and playback breaks, you have three suspects.
Save, and the proxy appears as a card on the dashboard.
Step 5 — Read the proxy card¶
Click a card's header to expand it. This is where you spend most of your operational time, so it is worth a proper look.
| Row | What it tells you |
|---|---|
| Host | The address clients should point at. Shows publicBaseURL when you have set one, otherwise the bind host and port. |
| Target | The upstream this proxy fronts. |
| Route | The egress path in force — System, VPN, TS Exit, or Direct. See Inbound & Outbound. |
| EPG | Auto-refresh state and when the guide was last pulled. |
| Logging | Per-proxy verbose toggle, and a Logs button that opens that proxy's live log ring buffer. |
| Xtream Account | Collapsible panel with the upstream credentials and the client-facing URL. |
| Proxy Connection | Collapsible panel with the ready-to-paste connection details for client apps. |
| Bandwidth / RPS | Live throughput and request rate for this proxy alone. |
The buttons at the bottom are the per-proxy actions: Play in the built-in player, browse Categories, Clone the proxy, open the OpenAPI explorer, Edit, or Delete.
Step 6 — Verify playback in the browser¶
Before you touch a TV app, prove the stream works from tunlx itself. Open the Web Player icon in the navbar and pick your proxy, or hit Play on the card.
Pick a category on the left, then a channel. If a stream starts here, tunlx is reaching your upstream and re-serving it correctly — everything after this is a client or a networking problem, not a tunlx one. The player's full feature set is covered in Web Player.
Xtream services ask for a viewer login
A Standard or Composite proxy plays straight away. An Xtream service is your own panel, so the player asks for one of the viewer logins you created for it before it will list anything.
Step 7 — Connect a real client¶
Expand Proxy Connection on the card to get the exact values. There are two ways to hand a lineup to a client app.
Most IPTV apps (TiviMate, IPTV Smarters, OTT Navigator) take these three fields:
| Field | Value |
|---|---|
| Server / Portal URL | http://<host>:<port> — for example http://203.0.113.10:9101 |
| Username | your proxy's Xtream username |
| Password | your proxy's Xtream password |
Under the hood the client calls player_api.php, which tunlx answers
directly:
A healthy response contains "auth": 1 and a server_info block.
Set publicBaseURL before going remote
tunlx writes stream URLs into the playlists it generates. If the proxy only
knows its LAN address, every URL in the playlist points at a LAN address and
remote clients fail after the login succeeds — a confusing failure mode.
Set publicBaseURL to the address clients actually reach you on
(https://tv.example.org) and the generated URLs follow.
Step 8 — Add reliability, one thing at a time¶
With baseline playback proven, turn features on individually and re-test between each.
Step 9 — Decide how traffic enters and leaves¶
Everything so far used plain public networking. The Networking dialog in the navbar sets both directions globally.
flowchart LR
subgraph IN [Inbound - where listeners bind]
I1[Public IP]
I2[Tailscale]
I3[Both]
end
subgraph TX [tunlx]
P[Proxies and services]
end
subgraph OUT [Outbound - where egress goes]
O1[Public ISP]
O2[WireGuard VPN]
O3[Tailscale exit node]
end
Clients --> IN --> TX --> OUT --> UpstreamsA per-proxy route overrides the global outbound setting, so one proxy can sit on the VPN while the rest go direct.
Fail-closed is not the default
By default, a proxy whose VPN or exit node is unavailable silently falls
back to your ISP connection. If that is unacceptable, enable
networking.failClosed globally or strictEgress on the individual proxy.
Those proxies then return 503 instead of leaking. Read
Inbound & Outbound before you rely on it.
Step 10 — Production checklist¶
- Admin password changed from the generated one.
-
publicBaseURLset on every proxy remote clients use. - Persistent
sessionSecret— otherwise sessions drop on every restart. -
config.jsonbacked up somewhere you can restore from. - Dashboard port 6060 firewalled off, or reachable only over Tailscale.
-
enforceHttpsenabled if you terminate TLS in front of tunlx. - Fail-closed egress configured if a VPN leak would matter.
-
config.key(next toconfig.json) backed up and never committed — without it the encrypted secrets in your config cannot be read.