Troubleshooting

Diagnose Tunnex in layers. First establish whether the control plane is alive, then whether it is ready, then whether the gateway reconciled, and finally whether the encrypted data path exchanged traffic.

cd tunnex
sudo docker compose -f tunnex.yml ps
sudo docker compose -f tunnex.yml exec -T api \
  wget -S -O- http://127.0.0.1:8080/healthz
sudo docker compose -f tunnex.yml exec -T api \
  wget -S -O- http://127.0.0.1:9090/readyz
sudo docker compose -f tunnex.yml logs --tail=200 api node-agent
sudo docker compose -f tunnex.yml exec -T node-agent wg show

Tunnex has no hosted relay. A gateway must be reachable through a public address, port-forward, or shared private network. A healthy control plane cannot compensate for an impossible peer path.

• Configuration was lost: revoke and re-issue it. Private keys and one-time profiles are not retrievable.
• Device exists but never connects: check Devices → Approvals. A client can hold a config while the device remains pending.
• New route is absent on an old profile: CLI and standard WireGuard profiles are static. Re-issue the profile, or use a managed desktop flow where supported.
• Access works before policies are enabled: policy enforcement starts disabled so initial connectivity is not locked out. Build and test default-deny policy, then enable enforcement deliberately.
• A grant is revoked while the gateway agent is down: new connections are denied when the agent returns, but already-established flows can survive the agent restart until they end naturally. A live policy removal performs a scoped conntrack flush when the gateway has that capability.
• Enforcement is re-enabled after being off: flows opened while enforcement was disabled are not retroactively flushed. Use a maintenance window when that distinction matters.
• OpenVPN revocation appears delayed: active clients are cut at their next TLS renegotiation; WireGuard revocation removes the peer immediately after reconcile.

The CLI has no status, doctor, or profile selector. Use sudo wg show, ip route, and the console as separate evidence.

1. Verify the downloaded checksum before installation.
2. Confirm the configured server’s /healthz is reachable and its TLS certificate is valid.
3. Complete browser authentication on the same desktop session.
4. Inspect the client state: Disconnected, Connecting, Connected, Reconnecting, or Blocked.
5. For a blocked kill switch, reconnect or intentionally disconnect through the client so its privileged helper removes the rules cleanly.

On Windows, full-tunnel sessions intentionally refuse gateway re-home rather than partially changing the default route. Disconnect and reconnect through the desired gateway. See Desktop client.

Use the callback values in SSO setup, copied exactly.

Record versions, edition metadata, timestamps, relevant health states, bounded logs, and sanitized route/handshake output. Never include:

• .env, master.key, session keys, or SMTP/SSO secrets;
• join tokens, device codes, bearer tokens, or authorization URLs;
• gateway certificates/private keys or complete WireGuard/OpenVPN profiles; or
• unredacted user identity and private resource names unless the recipient is authorized to receive them.