Skip to content

Gluetun — Reference

  • GitHub: https://github.com/qdm12/gluetun
  • Wiki (all providers): https://github.com/qdm12/gluetun-wiki
  • ProtonVPN setup: https://github.com/qdm12/gluetun-wiki/blob/main/setup/providers/protonvpn.md
  • Control server API: https://github.com/qdm12/gluetun-wiki/blob/main/setup/advanced/control-server.md
  • Docker Hub: https://hub.docker.com/r/qmcgaw/gluetun

Authentication

The Gluetun control server has no authentication. Access is restricted to the internal network.

curl -s http://192.168.1.110:8000/v1/...   # seedbox Gluetun
curl -s http://192.168.1.110:8001/v1/...   # normal Gluetun (if mapped to different port)

API — VPN Status

Get VPN status

curl -s http://192.168.1.110:8000/v1/openvpn/status | python3 -c \
  "import json,sys; d=json.load(sys.stdin); print(f'status={d[\"status\"]}')"

Returns running or stopped.

API — Public IP

Get current public IP

curl -s http://192.168.1.110:8000/v1/publicip/ip | python3 -c \
  "import json,sys; d=json.load(sys.stdin); print(f'ip={d[\"public_ip\"]} region={d.get(\"region\",\"?\")} country={d.get(\"country\",\"?\")}')"

API — Port Forwarding

Get forwarded port

curl -s http://192.168.1.110:8000/v1/openvpn/portforwarded | python3 -c \
  "import json,sys; d=json.load(sys.stdin); print(f'port={d[\"port\"]}')"

Returns 0 if port forwarding is not active or not supported by the provider.

API — Server Selection

Get current VPN server

curl -s http://192.168.1.110:8000/v1/openvpn/settings

Update VPN server

curl -s -X PUT http://192.168.1.110:8000/v1/openvpn/settings \
  -H "Content-Type: application/json" \
  -d '{"country": "Netherlands"}'

Triggers a reconnection to a server in the specified country.

API — DNS

Get DNS status

curl -s http://192.168.1.110:8000/v1/dns/status

API — Updater

Trigger VPN server list update

curl -s -X PUT http://192.168.1.110:8000/v1/updater/status \
  -H "Content-Type: application/json" \
  -d '{"status": "running"}'

Environment Variables (Key Config)

These are set in services/gluetun/docker-compose.yml:

Variable Purpose
VPN_SERVICE_PROVIDER Provider name (e.g., protonvpn)
VPN_TYPE wireguard or openvpn
WIREGUARD_PRIVATE_KEY WireGuard private key (from Vault)
SERVER_COUNTRIES Country filter for server selection
VPN_PORT_FORWARDING on to enable port forwarding
VPN_PORT_FORWARDING_UP_COMMAND Command to run when port is assigned (updates qBittorrent)
FIREWALL_VPN_INPUT_PORTS Ports allowed through the VPN firewall
HTTPPROXY on to enable HTTP proxy

VPN Leak Detection

Verify no traffic leaks outside the tunnel:

# From inside the qBittorrent container (via Gluetun network)
docker exec seedbox curl -s https://ipinfo.io/ip
# Should return the VPN IP, NOT your home IP

# Compare with Gluetun's reported IP
curl -s http://192.168.1.110:8000/v1/publicip/ip

What the API/CLI Cannot Do

Gap Workaround
Cannot configure WireGuard keys via API Set via environment variables in docker-compose
Cannot view connection logs via API Check Loki: {container="gluetun"}
Cannot restart the VPN tunnel via API (only change server) Restart the container: docker restart gluetun
No CLI tool Control server API only; use curl
Cannot configure firewall rules via API Set via FIREWALL_* environment variables
Cannot switch VPN providers without restarting Change VPN_SERVICE_PROVIDER env var and recreate the container
SOCKS5 not supported in current image Use HTTP proxy (HTTPPROXY=on) instead
Cannot check bandwidth usage via API Use Docker stats or Loki logs