Setup guide
From zero to operating: install, wizard, policies, doctor, and first connect. 15–20 minutes, step by step per operating system.
Kongtrol isn't a VPN client — it's the layer that sits between your apps and the VPN clients you already have installed (FortiClient, OpenVPN, ProtonVPN, etc.). The policy engine looks at every outbound connection (domain, IP or app) and decides which tunnel it should go through; the rest of the commands (up, doctor, status) just control that routing and the tunnels' lifecycle.
your apps
Chrome, Slack, terminal, code…
kongtrol
policy engine — domains · IPs · apps
your VPNs
Your VPNs are already installed and working. Kongtrol just orchestrates them — three commands and you're operating. The 10 sections below are reference; come back to them only if something doesn't fit.
- 1Register your profiles
Detects clients, stores credentials in the keychain, builds policies.
bash$ kongtrol init - 2Validate the stack
Binaries, certificates, keychain and permissions — before connecting.
bash$ kongtrol doctor - 3Connect and operate
Bring up a group, watch live status, open the dashboard.
bash$ kongtrol up --group work $ kongtrol status --watch $ kongtrol dashboard
Prerequisites
Kongtrol orchestrates the VPN clients you already have — it doesn't replace them. They need to be installed before you run kongtrol init.
| VPN | Required client | Check |
|---|---|---|
| FortiClient | FortiClient 6.4.x | Open FortiClient — at least one saved connection should appear in the list. If you can connect manually from the GUI, you're ready. |
| OpenVPN | OpenVPN Community | openvpn --version |
| WireGuard | wireguard-tools | wg --version |
| ProtonVPN | Official ProtonVPN app (or WireGuard with its .conf) | Sign in to the app. On Linux Kongtrol can connect for you; if not, you connect and it detects it. No app: a wireguard profile with Proton's .conf. |
| Cloudflare WARP | warp-cli | warp-cli --version |
| Command | Required client state |
|---|---|
| kongtrol init | Any — only reads files and the keychain |
| kongtrol doctor | Any — only validates, doesn't connect |
| kongtrol up <profile> | App installed; open or closed, either works (Kongtrol opens it if needed) |
Installation
$ curl -L https://github.com/DerotLuna/vpn-kongtrol/releases/latest/download/kongtrol_linux_amd64.tar.gz | tar xz $ sudo mv kongtrol /usr/local/bin/ # Verify $ kongtrol --help
One step as administrator: run kongtrol service install once and accept the prompt. It installs a helper that makes the network changes (routes, DNS, kill switch). After that no command needs an administrator terminal or sudo.
Registering your VPNs: kongtrol init
kongtrol init doesn't configure your VPNs — that's already done. What it does is tell Kongtrol where they are and how to talk to them: which client to use, what tunnel name it has, where the .ovpn lives, and it stores credentials in the OS keychain (never in the YAML).
If you already have FortiClient with a working tunnel and OpenVPN with its .ovpn, this step just collects that information.
Connection files
If your VPNs are already configured, you don't need to do anything special here. Kongtrol just points to the files where they already live — in the wizard you simply type each file's current path. You only need to act if you receive new files from a coworker or IT and have nowhere to put them, or if you want to reorganize everything into a single directory.
| Adapter | What the wizard needs | Anything to do? |
|---|---|---|
| FortiClient | Cert path, key path, credentials | Have the .crt and .key in some accessible path and note it down. |
| OpenVPN | Path to the .ovpn | No, if you already have the .ovpn. Just note its current path. |
| ProtonVPN | GUI mode: Proton credentials. Automatic mode: WireGuard .conf file. | GUI: no files. WireGuard: export the config from Proton and save the path. |
| WireGuard / others | Path to the config file | No, if you already have the file. Just note its path. |
~/.kongtrol/certs/ and copy the files there. Useful when onboarding a new teammate or receiving fresh certs. Not required if everything's already in place.Running the wizard
$ kongtrol init
You first pick a language, then the wizard shows the detected clients and asks whether you want to add a profile:
▸ VPN clients detected on this system: ✓ FortiClient 6.4.10.1821 ✓ OpenVPN 2.6.8 ✓ ProtonVPN 4.3.14 Add a new VPN profile? [y/N]: y
The wizard uses numbered menus where it makes sense — you don't have to memorize valid values:
Profile name: office Adapter type: 1) forticlient ✓ detected FortiClient SSL VPN 2) openvpn ✓ detected OpenVPN (.ovpn file) 3) protonvpn ✓ detected ProtonVPN (Proton account) ─────────────────────────────── 4) ciscoanyconnect Cisco AnyConnect 5) wireguard WireGuard (.conf file) 6) globalprotect Palo Alto GlobalProtect 7) tailscale Tailscale mesh / exit node 8) cloudflarewarp Cloudflare WARP Choose [1]: 1
Every field comes with a hint for where to find the value:
See the full field-by-field flow (FortiClient)
Find it in FortiClient > Settings or ask IT. e.g. vpn.company.com VPN host: vpn.yourcompany.com 443 for SSL VPN (default). Only change if IT tells you otherwise. Port [443]: The exact connection name as it appears in the FortiClient GUI list. Tunnel name [Office]: Office FortiClient version: 1) 6 6.4.x — most common 2) 7 7.x 3) 5 5.x — legacy Choose [1]: Auth method: 1) credentials username and password 2) certificate client certificate only 3) certificate+credentials certificate + username and password (more secure) Choose [3]: Client certificate path: ~/.kongtrol/certs/office.crt Private key path: ~/.kongtrol/certs/office.key Username: your_username Password for office (stored in keychain): ****
For OpenVPN, the wizard just points to your existing .ovpn file:
See the full field-by-field flow (OpenVPN)
Profile name: dev-server Adapter type: ... Choose [2]: 2 ← openvpn Full path to the .ovpn. Use its current location, no need to copy it. Path to .ovpn file: ~/.config/openvpn/server.ovpn If the .ovpn has <cert> and <key> embedded, choose 'certificate' and leave the paths blank. Auth method: 1) credentials username and password 2) certificate client certificate only 3) certificate+credentials certificate + username and password (more secure) Choose [2]: Client certificate path (blank if embedded in the .ovpn): Private key path (blank if embedded in the .ovpn):
ProtonVPN: manual GUI vs automatic WireGuard
There are two valid paths with ProtonVPN depending on how much you want to automate.
- Manual GUI (fast): you operate Proton from its app and Kongtrol routes policies over that profile.
- Automatic WireGuard (recommended): export a
.conffile from Proton, create atype: wireguardprofile and Kongtrol can bring the connection up/down by command.
vpns: us-content: type: wireguard config: ~/.kongtrol/configs/proton-us.conf auth: method: certificate
Open FortiClient → Remote Access tab. You'll see a list of saved connections. The connection name (e.g. "Office VPN") is the tunnel name. Click the pencil (edit) icon next to that connection — there you'll see the Remote Gateway or Server field: that's the host.
binary_path.At the end: security options, routing policies and confirmation:
See the security and policy flow
Enable kill switch? [Y/n]: Enable DNS guard? [Y/n]: Enable signed audit log? [Y/n]: Enable web dashboard? (http://127.0.0.1:9741) [Y/n]: Show your public IP? (asks an external service) [y/N]: Uses an external service (api.ipify.org) that sees your public IP ── Routing policies ────────────────────────────────────────────── Add a routing policy? [Y/n]: y Policy name (e.g. work, streaming): Claude AI VPN profile for this policy: 1) office 2) us-content Choose [1]: 2 Domain or suffix (e.g. company.com, .internal) — leave blank to finish Domain: claude.ai Domain: *.anthropic.com Domain: IP range or single IP (e.g. 10.0.0.0/8) — leave blank to finish IP / range: Add a routing policy? [Y/n]: y Policy name (e.g. work, streaming): Internal network VPN profile for this policy: 1) office 2) us-content Choose [1]: 1 Domain: IP / range: 10.10.0.0/16 IP / range: 192.168.50.0/24 IP / range: Add a routing policy? [Y/n]: You can also edit policies directly in kongtrol.yaml → 'policies' section. Write configuration to ~/.kongtrol/kongtrol.yaml? [Y/n]: y [✓] Configuration written to ~/.kongtrol/kongtrol.yaml [✓] Configuration is valid.
claude.ai, *.anthropic.com → two entries.kongtrol init again. The wizard detects the existing config and won't overwrite anything without confirmation.Groups
Groups bundle profiles so you can bring them up together with a single command. Edit ~/.kongtrol/kongtrol.yaml and append:
groups: work: profiles: [office, dev-server, aws] travel: profiles: [us-content] full: profiles: [office, dev-server, aws, us-content]
kongtrol up --group work # brings up office + dev-server + aws in parallel kongtrol down --group work
office can be in work and also in full without any conflict.If a daemon is already running (kongtrol up in the background, or via the dashboard) and you hand-edit the group, you don't need to restart it — kongtrol reload --group work re-reads kongtrol.yaml from disk and reconnects only that group's active tunnels. For a single tunnel, kongtrol reload --tunnel office.
Routing policies
When you have several tunnels active at once, how does your machine know which traffic goes over which VPN? That's what policies define.
request policy tunnel ────────────────────────────────────────────────────────────────────────── claude.ai ──▶ domains: claude.ai ──▶ us-content (ProtonVPN) 10.10.4.12 ──▶ ip_ranges: 10.10.0.0/16 ──▶ office (FortiClient) api.yourcompany.com ──▶ no match ──▶ direct connection (no VPN)
Without policies, each VPN installs its own routes on connect — the last one to connect usually wins general traffic, and you can't control what goes where. With policies, Kongtrol routes precisely:
claude.aiand*.anthropic.com→ go throughus-content(ProtonVPN)10.10.0.0/16(office network) → goes throughoffice(FortiClient)*.yourcompany.com→ goes throughoffice- Everything else → direct connection, no VPN
The wizard (kongtrol init) lets you create policies at the end of the flow. You can also add or edit them directly in the YAML under the policies: section:
policies: # ── US content / Claude AI ────────────────────────────────────────────── - name: Claude AI match: domains: - claude.ai - "*.anthropic.com" via: us-content - name: Geo-restricted content match: domains: - "*.netflix.com" - "*.hulu.com" - "*.disneyplus.com" via: us-content # ── Office ───────────────────────────────────────────────────────────── - name: Office internal network match: ip_ranges: - 10.10.0.0/16 # internal network — adjust to yours - 192.168.50.0/24 via: office - name: Internal domains match: domains: - "*.yourcompany.com" # change to your company's domain - intranet.local via: office # ── Dev server ───────────────────────────────────────────────────────── - name: Dev server match: ip_ranges: - 185.0.0.0/32 # replace with your server's real IP via: dev-server # ── AWS ──────────────────────────────────────────────────────────────── - name: AWS workloads match: ip_ranges: - 172.31.0.0/16 # AWS default VPC — adjust to your CIDRs domains: - "*.amazonaws.com" via: aws # Traffic that doesn't match any rule goes through your normal # connection (no VPN). To force EVERYTHING through one VPN: # - name: Default # match: # ip_ranges: [0.0.0.0/0] # via: office
Domains: exact glob or with a
*. prefix — *.company.com covers all subdomains but not company.com alone (add both if you need them).IPs: longest-prefix match — the most specific rule wins.
10.10.1.0/24 takes priority over 10.0.0.0/8.apps in a rule, but today it does not change routing: only domains and ip_ranges count. For now apps only shows up in kongtrol map app:<exe>.monitor.split_dns.enabled: true, Kongtrol injects policy domains into system resolution (hosts) so regular apps resolve through the right tunnel without calling the API.# Validate after editing $ kongtrol config validate # [OK] Config is valid.
kongtrol up. If one is already active, apply the change without restarting it via kongtrol reload --policy — reloads the policy engine from the edited kongtrol.yaml, without touching any tunnels.Verify with doctor
Before connecting for the first time, let Kongtrol validate everything's in order:
$ kongtrol doctor
Kongtrol Doctor ──────────────────────────────────────────────────── Configuration ✓ config file ~/.kongtrol/kongtrol.yaml ✓ config valid 4 profile(s) defined VPN Binaries ✓ forticlient FortiClient 6.4.10.1821 ✓ openvpn OpenVPN 2.6.8 ✓ protonvpn protonvpn-cli 4.3.14 Certificates & Keys ✓ office: cert ~/.kongtrol/certs/office.crt ✓ office: key ~/.kongtrol/certs/office.key ✓ dev-server: config ~/.kongtrol/configs/server.ovpn Keychain Credentials ✓ office: password found in OS keychain ✓ us-content: password found in OS keychain Permissions ✓ kill switch platform implementation available ✓ dns guard platform implementation available All checks passed. You're good to go.
If any line shows ✗, the message tells you exactly what's missing.
First connection
A whole group:
$ kongtrol up --group work [+] office connected [+] dev-server connected [+] aws connected
Several profiles without a group:
$ kongtrol up office dev-server aws
All three tunnels come up in parallel. The routing policy decides which traffic goes through which.
A single profile:
$ kongtrol up office $ kongtrol up us-content
Kongtrol keeps running in the background: closing the view disconnects nothing. When you're done:
# q or Ctrl+C → closes the view; the VPNs stay connected # To disconnect (from any terminal): $ kongtrol down --group work $ kongtrol down --all
Check status:
$ kongtrol status PROFILE STATUS IP UPTIME office connected 10.10.0.5 1h 23m dev-server connected 185.x.x.x 1h 23m aws connected 172.31.4.7 1h 23m us-content disconnected — — Kill switch: ARMED (protecting 3 tunnel(s)) # Live view (refreshes every 2s): $ kongtrol status --watch
Web dashboard
$ kongtrol dashboard # Dashboard running at http://127.0.0.1:9741
Open http://localhost:9741 in your browser. It's a full management console, with sidebar navigation:
| Page | What it does |
|---|---|
| Overview | Live tunnels, per-tunnel traffic charts, active routes, policy resolver, group quick-launch, connect/disconnect all |
| Studio | Tabs: routing policies (CRUD + rule tester), VPN profiles (CRUD, config + keychain), and groups (CRUD + connect/disconnect) |
| Security | Live Kill Switch/DNS Guard toggles, per-profile kill switch override, leak check status, optional public IP lookup (off by default) with a Check button |
| Audit Log | Audit events filterable by profile/level, with an HMAC-signed indicator |
| Settings | Health check, scheduler + rules, split DNS, kill switch/DNS guard tuning, public IP services, audit log |
# Useful endpoints GET /api/v1/metrics/history GET /api/v1/dns/resolve?domain=claude.ai&via=us-content GET /api/v1/resolve?target=portal.company.com&app=chrome.exe POST /api/v1/security/killswitch {"enabled": true} POST /api/v1/security/dnsguard {"enabled": true} POST /api/v1/security/publicip {"enabled": true} # optional: look up your public IP POST /api/v1/security/publicip/check # Check now GET /api/v1/vpns # profiles · POST/PUT/DELETE for CRUD GET /api/v1/groups # groups · POST/PUT/DELETE + /connect /disconnect GET /api/v1/settings # PUT to save GET /api/v1/audit # ?profile=&level=&limit=
kongtrol config dashboard set-port <port>) — changing it from the page serving the request would break the connection.Daily usage
| Command | What it does |
|---|---|
| kongtrol up --group work | Start the day (office + dev-server + aws) |
| kongtrol down --group work | End the day |
| kongtrol up us-content | Netflix, Hulu, Claude AI... |
| kongtrol down --all | Shut everything down |
| kongtrol status | See what's connected |
| kongtrol status --watch | Live monitoring (2s) |
| kongtrol status --watch --dashboard | Live monitoring + starts the embedded dashboard at the same time |
| kongtrol check | Look up your public IP and test for leaks now (if you turned the lookup on) |
| kongtrol dashboard | Open the web UI |
| kongtrol doctor | Full diagnostics |
| kongtrol export | Export config without passwords (to share) |
Optional time-based scheduler:
monitor: scheduler: enabled: true interval: "1m" rules: - name: "work-hours" profiles: ["office", "aws"] weekdays: ["mon","tue","wed","thu","fri"] start: "09:00" end: "18:00"
Per-profile kill switch override:
vpns: office: kill_switch: true us-content: kill_switch: false
Update a password:
$ kongtrol init # → pick the profile → "Update credentials?" → enter the new one
Command reference
The same groups as kongtrol --help. Every command has its own help with examples: kongtrol <command> --help.
| Connection | What it does |
|---|---|
| kongtrol up [profile...] [flags] --all --dry-run --fav --group group | Connect one or more VPN profiles (or all with --all) |
| kongtrol down [profile...] [flags] --all --group group | Disconnect one or more VPN profiles (or a group with --group) |
| kongtrol status [flags] --dashboard -w, --watch | Show the status of all VPN tunnels |
| kongtrol routes [profile] [flags] | Show what goes through each tunnel |
| kongtrol routes list [flags] | List the system routes Kongtrol added |
| kongtrol map [target|app:<exe>] [flags] | Show which VPN each destination uses |
| kongtrol dashboard [flags] | Open the web dashboard in your browser |
| Setup | What it does |
|---|---|
| kongtrol init [flags] | Wizard to create or update your setup |
| kongtrol config [command] | Validate the config and adjust this computer |
| kongtrol config validate [flags] | Validate kongtrol.yaml without connecting |
| kongtrol config favorites [command] | Manage your favorite profiles |
| kongtrol config favorites list [flags] | List your favorite profiles |
| kongtrol config favorites add <profile> [flags] | Add a profile to favorites |
| kongtrol config favorites remove <profile> [flags] | Remove a profile from favorites |
| kongtrol config defaults [command] | Set what kongtrol up connects with no arguments |
| kongtrol config defaults show [flags] | Show the default group |
| kongtrol config defaults set-group <group> [flags] | Set the group kongtrol up connects |
| kongtrol config lang <es|en> [flags] | Change Kongtrol's language in the terminal |
| kongtrol config dashboard [command] | Set the dashboard's local address and port |
| kongtrol config dashboard show [flags] | Show the dashboard address and port |
| kongtrol config dashboard set-port <port> [flags] | Change the dashboard's local port (applies on restart) |
| kongtrol config dashboard set-bind <address> [flags] | Change the dashboard's local address (applies on restart) |
| kongtrol config dashboard reset [flags] | Clear the local setting and go back to kongtrol.yaml |
| kongtrol config public-ip <on|off> [flags] | Turn the public IP lookup on or off |
| kongtrol policy [command] | Check and test your traffic policies |
| kongtrol policy explain <target|app:<exe>> [flags] | Explain which policy matches and why |
| kongtrol policy test <file> [flags] | Test your policies against a list of destinations |
| kongtrol reload [flags] --group group --policy --tunnel profile | Apply kongtrol.yaml changes without disconnecting |
| kongtrol restart [flags] | Restart Kongtrol to use new or edited VPN profiles |
| kongtrol export [flags] | Print your config without secrets to share it |
| Diagnostics | What it does |
|---|---|
| kongtrol doctor [flags] --fix | Check your computer: programs, certificates, keychain, permissions |
| kongtrol check [flags] | Look up your public IP now and check for leaks |
| kongtrol logs [flags] --daemon -f, --follow --level level --profile profile --tail N | Show Kongtrol's events |
| System | What it does |
|---|---|
| kongtrol service [command] | Install or check the Kongtrol helper (no admin terminal) |
| kongtrol service install [flags] | Install the helper once (asks for admin permission) |
| kongtrol service uninstall [flags] | Remove the helper from this computer |
| kongtrol service status [flags] | Show whether the helper is installed and responding |
| kongtrol version [flags] | Show Kongtrol's version |
| kongtrol help [command] [flags] | Show help for a command |
| Global flags | What it does |
|---|---|
| --alert-bell | ring bell on critical alerts |
| -c, --config path | config file path (default: ~/.kongtrol/kongtrol.yaml) |
| -h, --help | help for kongtrol |
| --json | emit JSON output for automation |
| --plain | plain ASCII output (no color and no Unicode symbols) |
| -q, --quiet | reduce non-essential output (no banner/spinner) |
Troubleshooting
DNS not restored after a crash:
$ sudo cp /etc/resolv.conf.kongtrol.bak /etc/resolv.conf
Kill switch still active with no internet after disconnecting:
$ kongtrol down --all # disables the kill switch automatically
If Kongtrol closed abruptly: with the helper installed, its blocks lift on their own in about 20 seconds (the network stays open, never cut). If they're still there, remove only Kongtrol's rules. Don't use netsh advfirewall reset: it deletes all your firewall rules.
$ sudo iptables -F OUTPUT
The VPN client isn't showing up in auto-detection:
# The wizard asks for the binary path if it can't detect it: $ kongtrol init # ! This VPN client wasn't auto-detected. # Binary path (blank = auto-detect): /path/to/binary # Or add it manually in ~/.kongtrol/kongtrol.yaml: # office: # type: forticlient # app_path: "/custom/path/FortiClient"
Cloudflare WARP — "not registered":
$ warp-cli register
Wrong or expired password:
$ kongtrol init # Select the profile → "Refresh credentials" → enter the new one
File layout:
~/.kongtrol/ ├── kongtrol.yaml ← main config (no passwords) ├── certs/ │ ├── office.crt │ └── office.key ├── configs/ │ ├── server.ovpn │ └── aws.ovpn └── audit.log ← signed log of every event Passwords stored in: Windows → Windows Credential Manager macOS → Keychain Linux → libsecret / GNOME Keyring