CLI & Environment
Everything tunlx can be told at startup, including flags, environment
variables, and the file paths it cares about.
Command-line flags
./tunlx -configFile=/etc/tunlx/config.json
| Flag |
Default |
Purpose |
-configFile |
./config.json |
Path to the JSON configuration. Auto-created on first run if missing. |
-dashboardPort |
6060 |
Override the dashboard port without editing config. |
-thisServerHost |
— |
Override proxies[].thisServerHost for the legacy single-proxy mode. |
-thisServerPort |
— |
Same, but for the listen port. |
-targetServer |
— |
Same, but for the upstream URL. |
-debug / -v |
false |
Verbose logging at startup. Equivalent to TUNLX_DEBUG=true. |
--xtremeWizard |
— |
Launch the interactive Xtream CLI wizard and exit. |
Environment variables
Environment overrides are useful for container deployments and CI.
Core
| Variable |
Equivalent in config |
Purpose |
TUNLX_DEBUG |
— |
true enables verbose startup logs. |
TUNLX_DASHBOARD_PORT |
dashboardPort |
Dashboard port. |
TUNLX_SESSION_SECRET |
sessionSecret |
32-byte key (base64 / hex / 32-char ASCII) for session cookies. |
WireGuard
| Variable |
Equivalent in config |
Purpose |
TUNLX_WG_IFACE |
— |
Interface name when route: vpn (default wg0). |
TUNLX_WG_CONF |
vpn.manual.configPath |
Path to the WireGuard config (default /etc/wireguard/<iface>.conf). |
TUNLX_WG_AUTOSTART |
vpn.autoStartOnBoot |
Enable the systemd unit for the interface (Linux). |
TUNLX_WG_MARK |
— |
Firewall mark (SO_MARK) on WireGuard sockets. |
| Variable |
Equivalent in config |
Purpose |
TUNLX_MEDIAFLOW_BASE_URL |
proxies[].mediaFlowURL |
Fallback when a proxy doesn't override the URL. |
API_PASSWORD |
— |
Default API password for MediaFlow requests. |
MEDIAFLOW_API_PASSWORD |
— |
Fallback if API_PASSWORD is unset. |
Tailscale (embedded tsnet)
These take effect at startup. Precedence is config.json → these env
vars → defaults (see tailnet_config.go).
| Variable |
Equivalent in config |
Purpose |
TUNLX_TS_ENABLED |
tailscale.enabled |
Turn the embedded tsnet node on. |
TUNLX_TS_HOSTNAME |
tailscale.hostname |
Hostname advertised to the Tailnet (default tunlx). |
TUNLX_TS_STATE_DIR |
tailscale.stateDir |
Where the node persists state (default: config dir). |
TUNLX_TS_CONTROL_URL |
— |
Custom Headscale / control plane URL. |
TUNLX_TS_EPHEMERAL |
tailscale.ephemeral |
Register as an ephemeral node. |
TS_AUTHKEY |
— |
Standard Tailscale auth key for first-time login. |
Install-time (for install.sh --silent)
| Variable |
Purpose |
TUNLX_ADMIN_PASSWORD |
Set the initial admin password non-interactively. |
TUNLX_TAILSCALE_ONLY |
Set to 1 to bind only on the Tailnet. |
TUNLX_TAILSCALE_AUTHKEY |
Auth key the installer passes to the Tailscale node. |
TUNLX_TAILSCALE_HOSTNAME |
Hostname for the Tailscale sidecar. |
File locations
| Path |
Purpose |
/app/data/config.json (container) |
Default config file location inside the official image. |
./config.json (binary) |
Default when running the binary directly. |
examples/config.example.json |
Canonical sample with every field documented. |
/etc/wireguard/wg0.conf |
Conventional path for the manual-mode WireGuard config. |
<stateDir>/tailscale |
tsnet state when Tailscale is enabled. |
Admin HTTP endpoints
A short list of endpoints the dashboard uses — handy for scripting:
| Method |
Path |
Purpose |
GET |
/metrics |
Host CPU / memory / network-IO JSON (container health) |
GET |
/outbound-ip |
Detected egress IP (VPN-aware) |
GET |
/outbound-ip/non-vpn |
Egress IP via system route |
GET |
/tailnet/status |
Embedded Tailscale node state |
GET |
/tailnet/peers |
Tailnet exit-node candidates |
POST |
/tailnet/action |
Apply exit-node selection |
GET |
/tailnet/config |
Tailscale config snapshot |
POST |
/networking/config |
Set inbound + outbound modes |
POST |
/process/restart |
In-place re-exec (used after listener changes) |
GET |
/xtreme-service/tests |
Stream health test status |
GET |
/xtreme-service/tests/history |
Past stream-test results |
GET |
/integrations/iptv-org/metadata |
Available countries / categories from iptv-org |
POST |
/integrations/iptv-org/refresh |
Force-refresh the iptv-org cache |
POST |
/setup/state |
Mark dashboard onboarding complete |
All endpoints except /metrics require an authenticated session (admin
cookie) and sit behind the same rate limiters that protect the login and EPG
endpoints. /metrics is deliberately unauthenticated so the container health
check can reach it — treat the dashboard port as private and keep it
firewalled from the public internet.
Quick "what's running" checklist
# Process is up?
curl -s http://localhost:6060/metrics | head
# What does egress look like right now?
curl -s http://localhost:6060/outbound-ip
curl -s http://localhost:6060/outbound-ip/non-vpn
# Tailscale up?
curl -s http://localhost:6060/tailnet/status
# Container logs (Docker / Compose)
docker logs --tail=200 tunlx