# qdm12/gluetun architecture

> Architecture diagram of the GitHub repository qdm12/gluetun, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qdm12/gluetun
- Repository: https://github.com/qdm12/gluetun

## Overview

Gluetun is a VPN client that configures a protected network environment, connects through many VPN providers, and offers supporting DNS, proxy, port-forwarding, and operational services. The main executable reads settings and sets up routing and firewalling; provider-specific modules and VPN implementations supply the connection choices. The README documents additional capabilities whose detailed wiring is not shown in the excerpts, so those links are documented at the subsystem level. Source excerpts show only part of startup, so unspecified runtime relationships are omitted.

Main entry points: [`cmd/gluetun/main.go`](https://github.com/qdm12/gluetun/blob/master/cmd/gluetun/main.go) (Application startup), [`internal/vpn/tunnelup.go`](https://github.com/qdm12/gluetun/blob/master/internal/vpn/tunnelup.go) (VPN lifecycle), [`internal/provider/providers.go`](https://github.com/qdm12/gluetun/blob/master/internal/provider/providers.go) (VPN providers), [`internal/storage/storage.go`](https://github.com/qdm12/gluetun/blob/master/internal/storage/storage.go) (Server catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and settings"]
  node_main["Application startup<br/>[main.go]"]
  node_settings["Settings<br/>[settings.go]"]
  node_fileconfig["File configuration<br/>[reader.go]"]
end

subgraph group_connection["VPN connection"]
  node_providers["VPN providers<br/>[providers.go]"]
  node_serverdata[("Server catalog<br/>[storage.go]")]
  node_servermodel["Server records<br/>[server.go]"]
  node_vpn["VPN lifecycle<br/>[tunnelup.go]"]
  node_openvpn["OpenVPN<br/>[openvpn.go]"]
  node_wireguard["WireGuard<br/>[run.go]"]
  node_amnezia["AmneziaWG<br/>[run.go]"]
end

subgraph group_network["Network protection"]
  node_routing["Network routing<br/>[routing.go]"]
  node_firewall["Kill-switch firewall<br/>[iptables.go]"]
end

subgraph group_services["Runtime services"]
  node_dns["DNS and filtering<br/>[run.go]"]
  node_portforward["Port forwarding<br/>[loop.go]"]
  node_socks5["SOCKS5 proxy<br/>[server.go]"]
  node_httpproxy["HTTP proxy<br/>[server.go]"]
  node_shadowsocks["Shadowsocks proxy<br/>[loop.go]"]
  node_health["Health checks<br/>[server.go]"]
  node_metrics["Prometheus metrics<br/>[server.go]"]
  node_control["Control API<br/>[server.go]"]
  node_publicip["Public IP lookup<br/>[loop.go]"]
end

node_user(("Operator"))

node_user -->|"starts"| node_main
node_main -->|"reads"| node_settings
node_main -->|"configures reader"| node_fileconfig
node_main -->|"sets up"| node_routing
node_main -->|"configures"| node_firewall
node_main -->|"starts"| node_portforward
node_main -->|"starts"| node_socks5
node_main -->|"starts"| node_health
node_main -->|"starts"| node_metrics
node_main -->|"creates"| node_control
node_main -->|"initializes"| node_providers
node_providers -->|"uses"| node_serverdata
node_serverdata -->|"stores"| node_servermodel
node_providers -.->|"selects connection"| node_vpn
node_vpn -.->|"supports"| node_openvpn
node_vpn -.->|"supports"| node_wireguard
node_vpn -.->|"supports"| node_amnezia
node_main -.->|"runs"| node_dns
node_main -.->|"runs"| node_httpproxy
node_main -.->|"runs"| node_shadowsocks
node_main -.->|"runs"| node_publicip
node_vpn -.->|"enables"| node_portforward
node_main -->|"protects traffic"| node_firewall

click node_main "https://github.com/qdm12/gluetun/blob/master/cmd/gluetun/main.go"
click node_settings "https://github.com/qdm12/gluetun/blob/master/internal/configuration/settings/settings.go"
click node_fileconfig "https://github.com/qdm12/gluetun/blob/master/internal/configuration/sources/files/reader.go"
click node_providers "https://github.com/qdm12/gluetun/blob/master/internal/provider/providers.go"
click node_serverdata "https://github.com/qdm12/gluetun/blob/master/internal/storage/storage.go"
click node_servermodel "https://github.com/qdm12/gluetun/blob/master/internal/models/server.go"
click node_vpn "https://github.com/qdm12/gluetun/blob/master/internal/vpn/tunnelup.go"
click node_openvpn "https://github.com/qdm12/gluetun/blob/master/internal/openvpn/openvpn.go"
click node_wireguard "https://github.com/qdm12/gluetun/blob/master/internal/wireguard/run.go"
click node_amnezia "https://github.com/qdm12/gluetun/blob/master/internal/amneziawg/run.go"
click node_routing "https://github.com/qdm12/gluetun/blob/master/internal/routing/routing.go"
click node_firewall "https://github.com/qdm12/gluetun/blob/master/internal/firewall/iptables/iptables.go"
click node_dns "https://github.com/qdm12/gluetun/blob/master/internal/dns/run.go"
click node_portforward "https://github.com/qdm12/gluetun/blob/master/internal/portforward/loop.go"
click node_socks5 "https://github.com/qdm12/gluetun/blob/master/internal/socks5/server.go"
click node_httpproxy "https://github.com/qdm12/gluetun/blob/master/internal/httpproxy/server.go"
click node_shadowsocks "https://github.com/qdm12/gluetun/blob/master/internal/shadowsocks/loop.go"
click node_health "https://github.com/qdm12/gluetun/blob/master/internal/healthcheck/server.go"
click node_metrics "https://github.com/qdm12/gluetun/blob/master/internal/metrics/prometheus/server.go"
click node_control "https://github.com/qdm12/gluetun/blob/master/internal/server/server.go"
click node_publicip "https://github.com/qdm12/gluetun/blob/master/internal/publicip/loop.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_settings,node_fileconfig toneBlue
class node_providers,node_serverdata,node_servermodel,node_vpn,node_openvpn,node_wireguard,node_amnezia toneAmber
class node_routing,node_firewall toneMint
class node_dns,node_portforward,node_socks5,node_httpproxy,node_shadowsocks,node_health,node_metrics,node_control,node_publicip toneRose
class node_user toneIndigo
```

## Components

### Startup and settings

- [Application startup](https://github.com/qdm12/gluetun/blob/master/cmd/gluetun/main.go): `cmd/gluetun/main.go`
- [Settings](https://github.com/qdm12/gluetun/blob/master/internal/configuration/settings/settings.go): `internal/configuration/settings/settings.go`
- [File configuration](https://github.com/qdm12/gluetun/blob/master/internal/configuration/sources/files/reader.go): `internal/configuration/sources/files/reader.go`

### VPN connection

- [VPN providers](https://github.com/qdm12/gluetun/blob/master/internal/provider/providers.go): `internal/provider/providers.go`
- [Server catalog](https://github.com/qdm12/gluetun/blob/master/internal/storage/storage.go): `internal/storage/storage.go`
- [Server records](https://github.com/qdm12/gluetun/blob/master/internal/models/server.go): `internal/models/server.go`
- [VPN lifecycle](https://github.com/qdm12/gluetun/blob/master/internal/vpn/tunnelup.go): `internal/vpn/tunnelup.go`
- [OpenVPN](https://github.com/qdm12/gluetun/blob/master/internal/openvpn/openvpn.go): `internal/openvpn/openvpn.go`
- [WireGuard](https://github.com/qdm12/gluetun/blob/master/internal/wireguard/run.go): `internal/wireguard/run.go`
- [AmneziaWG](https://github.com/qdm12/gluetun/blob/master/internal/amneziawg/run.go): `internal/amneziawg/run.go`

### Network protection

- [Network routing](https://github.com/qdm12/gluetun/blob/master/internal/routing/routing.go): `internal/routing/routing.go`
- [Kill-switch firewall](https://github.com/qdm12/gluetun/blob/master/internal/firewall/iptables/iptables.go): `internal/firewall/iptables/iptables.go`

### Runtime services

- [DNS and filtering](https://github.com/qdm12/gluetun/blob/master/internal/dns/run.go): `internal/dns/run.go`
- [Port forwarding](https://github.com/qdm12/gluetun/blob/master/internal/portforward/loop.go): `internal/portforward/loop.go`
- [SOCKS5 proxy](https://github.com/qdm12/gluetun/blob/master/internal/socks5/server.go): `internal/socks5/server.go`
- [HTTP proxy](https://github.com/qdm12/gluetun/blob/master/internal/httpproxy/server.go): `internal/httpproxy/server.go`
- [Shadowsocks proxy](https://github.com/qdm12/gluetun/blob/master/internal/shadowsocks/loop.go): `internal/shadowsocks/loop.go`
- [Health checks](https://github.com/qdm12/gluetun/blob/master/internal/healthcheck/server.go): `internal/healthcheck/server.go`
- [Prometheus metrics](https://github.com/qdm12/gluetun/blob/master/internal/metrics/prometheus/server.go): `internal/metrics/prometheus/server.go`
- [Control API](https://github.com/qdm12/gluetun/blob/master/internal/server/server.go): `internal/server/server.go`
- [Public IP lookup](https://github.com/qdm12/gluetun/blob/master/internal/publicip/loop.go): `internal/publicip/loop.go`

### Other components

- **Operator**

## Connections

- Operator → Application startup: starts
- Application startup → Settings: reads (evidence: `cmd/gluetun/main.go`)
- Application startup → File configuration: configures reader (evidence: `cmd/gluetun/main.go`)
- Application startup → Network routing: sets up (evidence: `cmd/gluetun/main.go`)
- Application startup → Kill-switch firewall: configures (evidence: `cmd/gluetun/main.go`)
- Application startup → Port forwarding: starts (evidence: `cmd/gluetun/main.go`)
- Application startup → SOCKS5 proxy: starts (evidence: `cmd/gluetun/main.go`)
- Application startup → Health checks: starts (evidence: `cmd/gluetun/main.go`)
- Application startup → Prometheus metrics: starts (evidence: `cmd/gluetun/main.go`)
- Application startup → Control API: creates (evidence: `cmd/gluetun/main.go`)
- Application startup → VPN providers: initializes (evidence: `cmd/gluetun/main.go`)
- VPN providers → Server catalog: uses
- Server catalog → Server records: stores (evidence: `internal/storage/storage.go`)
- VPN providers → VPN lifecycle: selects connection
- VPN lifecycle → OpenVPN: supports
- VPN lifecycle → WireGuard: supports
- VPN lifecycle → AmneziaWG: supports
- Application startup → DNS and filtering: runs
- Application startup → HTTP proxy: runs
- Application startup → Shadowsocks proxy: runs
- Application startup → Public IP lookup: runs
- VPN lifecycle → Port forwarding: enables
- Application startup → Kill-switch firewall: protects traffic
