Installation

You have three ways to install tunlx. Pick the one that matches how you already deploy software.

One-line installer Fastest path on a fresh Linux host. Installs Docker, deploys tunlx, writes a starter config, optionally locks down to Tailscale.

Docker Compose For operators who want to own the stack. Start from the repo's compose file and adjust.

Native binary Build from source with Go 1.26+. Drop the binary anywhere and point it at a config file.

Prerequisites

• Linux host (Debian / Ubuntu recommended for the installer; any modern distro works for Docker / native)
• Root or sudo access
• Outbound internet access for image / package downloads

Choose your path

Installer (recommended)Docker ComposeNative binary

The installer brings up everything you need on a clean host.

curl -fsSL https://raw.githubusercontent.com/eyupio/tunlx/main/install.sh | bash

What it does:

• Installs missing dependencies (docker, docker compose, htpasswd, iptables persistence helpers).
• Pulls ghcr.io/eyupio/tunlx:latest.
• Prompts for admin credentials and dashboard bind settings.
• Optionally enables Tailscale-only access.
• Optionally configures WireGuard helper scripts.

After it finishes, open http://<host-ip>:6060 and sign in with the credentials it printed.

Silent install for CI / automation

TUNLX_ADMIN_PASSWORD='change-me-now' \
TUNLX_TAILSCALE_ONLY=1 \
TUNLX_TAILSCALE_AUTHKEY='tskey-auth-XXXXXXXX' \
TUNLX_TAILSCALE_HOSTNAME='tunlx' \
bash install.sh --silent

Run with -n (dry-run) to see what it would do without changing anything. See CLI & Environment for every flag.

Use this when you manage your own stack and want to keep tunlx as one service among others.

cp docker-compose.yaml docker-compose.local.yaml

Minimal example:

services:
  tunlx:
    container_name: tunlx
    image: ghcr.io/eyupio/tunlx:latest
    restart: unless-stopped
    environment:
      - commandLine=-configFile=/app/data/config.json
    volumes:
      - ./data:/app/data
    network_mode: host

Start it:

docker compose -f docker-compose.local.yaml up -d

Notes:

• network_mode: host keeps proxy listeners reachable without per-port mapping.
• Keep config.json under ./data/config.json for the default path.
• Add NET_ADMIN, NET_RAW, and /dev/net/tun only if you need in-container WireGuard routing.

A gluetun-sidecar compose variant lives under deployments/docker/ in the repo.

Build it from source.

git clone https://github.com/eyupio/tunlx.git
cd tunlx
go build -o tunlx .
./tunlx -configFile=/etc/tunlx/config.json

First start auto-creates config.json if it's missing. From there, sign in to http://<host>:6060 and start configuring.

Post-install validation

1. Sign in. Open the dashboard and confirm your credentials work.
2. Check metrics. curl http://localhost:6060/metrics should return JSON.
3. Create your first proxy. Follow the Quick Start.
4. If using WireGuard, verify wg show reports an interface before relying on route: vpn.

Restrict to Tailscale (any time)

You can switch any installation to Tailnet-only access. Either follow Tailscale Access for the embedded-node path, or use the sidecar pattern documented there for older deployments.

Upgrade

ContainerBinary

docker compose pull
docker compose up -d

Config and state in ./data persist across pulls.

Rebuild from main (or check out a tag), drop the new binary in place, and restart your unit / process. config.json is forward-compatible between minor versions — unknown fields are ignored.

Where to next

Quick Start Get a working proxy with playback verification in five minutes. Get started

Setup Wizards Use the dashboard onboarding or the CLI wizard for a guided first run. Walk through it

Tailscale Access Lock the dashboard to your Tailnet from day one. Tailnet-only setup