traefik-viz

Visualize your Traefik reverse proxy topology from the terminal. See all HTTP and TCP routes, their backends, live health status, TLS errors with fix suggestions, and config file locations — in one glance.

Quick start

npx traefik-viz

Or install globally:

npm install -g traefik-viz
traefik-viz

Example output

  Traefik v3.3.3 | 5 HTTP routes, 1 TCP routes | providers: docker, file

  https://app.localhost        [200] -> app          -> http://172.18.0.5:3000 [UP]
  https://api.localhost        [200] -> api          -> http://172.18.0.3:8080 [UP]
  https://grafana.localhost    [200] -> grafana      -> http://172.18.0.7:3000 [UP]
  https://pg.localhost         [TLS] -> pgweb        -> http://172.18.0.4:8081 [UP]
  http://whoami.localhost      [200] -> whoami       -> http://172.18.0.2:80   [UP]
  tcp://db:5432                       -> postgres     -> 172.18.0.6:5432       [UP]

  Errors:
  TLS  DEPTH_ZERO_SELF_SIGNED_CERT — self-signed cert not trusted
       fix: run: mkcert -install (installs the local CA into your trust store)
       on: https://pg.localhost

  Config:
  static   /opt/homebrew/etc/traefik/traefik.toml
  dynamic  /opt/homebrew/etc/traefik/dynamic.toml
  certs    /opt/homebrew/etc/traefik/certs/ (4 pem files)
  log      /opt/homebrew/var/log/traefik.log (128KB)

Features

• HTTP & TCP routes — shows all enabled routers with their hosts, services, and backends
• Live probing — sends HEAD requests to every HTTP route and reports status codes
• TLS error diagnosis — identifies cert issues (expired, self-signed, wrong hostname) with actionable fix tips
• Conflict detection — warns when multiple services share a host or backend
• Config file discovery — finds static/dynamic config, cert directory, and log file
• Certificate validation — checks that referenced cert/key files exist on disk
• Backend health — shows UP/DOWN status for each load balancer server
• Zero dependencies — uses only Node.js builtins and the Fetch API

Configuration

By default, traefik-viz connects to the Traefik API at http://localhost:8080.

Override with the TRAEFIK_API environment variable:

TRAEFIK_API=http://traefik.local:9090 traefik-viz

Traefik API setup

The Traefik API must be enabled. Add to your Traefik static config:

[api]
  insecure = true   # exposes on :8080

Or via CLI flag: --api.insecure=true

Output explained

Each line shows:

  <protocol>://<host>  [<status>] -> <service> -> <backend-url> [<health>]

| Column | Description | |--------|-------------| | protocol://host | The route's entrypoint protocol and matched hostname | | [status] | HTTP probe result — status code (200, 301, 404...) or error label | | service | Traefik service name (without provider suffix) | | backend-url | Load balancer server URL | | [health] | Backend health from Traefik: UP or DOWN |

Error codes

| Label | Meaning | |-------|---------| | TLS | TLS/certificate error (expired, self-signed, wrong hostname, incomplete chain) | | DNS | DNS lookup failed — hostname not resolvable | | REFUSED | Connection refused — nothing listening on the port | | TIMEOUT | No response within 3 seconds | | RESET | Connection reset by the server | | ERR | Other/unknown error |

Each error includes a fix: suggestion and the affected hosts.

Requirements

• Node.js 18+ (for native fetch)
• Traefik with the API enabled (--api.insecure=true or equivalent)

Development

git clone https://github.com/ktamas77/traefik-viz.git
cd traefik-viz
npm install
npm run build
npm run lint
npm run format:check
npm run typecheck
node dist/index.js

License

MIT