Setup guide

From zero to operating: install, wizard, policies, doctor, and first connect. 15–20 minutes, step by step per operating system.

How it works

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

FortiClientoffice
OpenVPNdev-server
ProtonVPNus-content
Quickstart

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.

  1. 1
    Register your profiles

    Detects clients, stores credentials in the keychain, builds policies.

    bash
    $ kongtrol init
    
  2. 2
    Validate the stack

    Binaries, certificates, keychain and permissions — before connecting.

    bash
    $ kongtrol doctor
    
  3. 3
    Connect and operate

    Bring up a group, watch live status, open the dashboard.

    bash
    $ kongtrol up --group work
    $ kongtrol status --watch
    $ kongtrol dashboard
    
1

Prerequisites

Kongtrol orchestrates the VPN clients you already have — it doesn't replace them. They need to be installed before you run kongtrol init.

VPNRequired clientCheck
FortiClientFortiClient 6.4.xOpen FortiClient — at least one saved connection should appear in the list. If you can connect manually from the GUI, you're ready.
OpenVPNOpenVPN Communityopenvpn --version
WireGuardwireguard-toolswg --version
ProtonVPNOfficial 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 WARPwarp-cliwarp-cli --version
Keep your VPN app: Kongtrol works with it. If the tunnel is already up, it attaches to it. If not, it opens the app and connects for you where it can; if it can't, it tells you what to do and waits for you to connect.
CommandRequired client state
kongtrol initAny — only reads files and the keychain
kongtrol doctorAny — only validates, doesn't connect
kongtrol up <profile>App installed; open or closed, either works (Kongtrol opens it if needed)
2

Installation

bash
$ 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.

3

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.

AdapterWhat the wizard needsAnything to do?
FortiClientCert path, key path, credentialsHave the .crt and .key in some accessible path and note it down.
OpenVPNPath to the .ovpnNo, if you already have the .ovpn. Just note its current path.
ProtonVPNGUI mode: Proton credentials. Automatic mode: WireGuard .conf file.GUI: no files. WireGuard: export the config from Proton and save the path.
WireGuard / othersPath to the config fileNo, if you already have the file. Just note its path.
Optional organization: if you want to centralize things, you can create ~/.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

bash
$ kongtrol init

You first pick a language, then the wizard shows the detected clients and asks whether you want to add a profile:

text
▸  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:

text
  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)
text
    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)
text
  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 .conf file from Proton, create a type: wireguard profile and Kongtrol can bring the connection up/down by command.
yaml
vpns:
  us-content:
    type: wireguard
    config: ~/.kongtrol/configs/proton-us.conf
    auth:
      method: certificate
ProtonVPN alongside other adapters (Forti/OpenVPN/etc.): use it in a separate profile and only route target domains/IPs (e.g. streaming). Keep corporate traffic in its dedicated profiles to avoid route conflicts.
Where do I find FortiClient's Host and Tunnel Name?
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.
If a client isn't auto-detected, the wizard tells you and asks for the binary path. You can also set it later in the YAML with binary_path.

At the end: security options, routing policies and confirmation:

See the security and policy flow
text
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.
You can type several domains separated by commas in a single prompt — the wizard splits them automatically. claude.ai, *.anthropic.com → two entries.
To add another profile or policy later: run kongtrol init again. The wizard detects the existing config and won't overwrite anything without confirmation.
4

Groups

Groups bundle profiles so you can bring them up together with a single command. Edit ~/.kongtrol/kongtrol.yaml and append:

yaml
groups:
  work:
    profiles: [office, dev-server, aws]

  travel:
    profiles: [us-content]

  full:
    profiles: [office, dev-server, aws, us-content]
bash
kongtrol up --group work     # brings up office + dev-server + aws in parallel
kongtrol down --group work
A profile can belong to several groups at once — 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.

5

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.

text
  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.ai and *.anthropic.com → go through us-content (ProtonVPN)
  • 10.10.0.0/16 (office network) → goes through office (FortiClient)
  • *.yourcompany.com → goes through office
  • 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:

yaml
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
How does matching work?
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.
App rules (experimental): you can write 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>.
Transparent split-DNS: with 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.
bash
# Validate after editing
$ kongtrol config validate
# [OK] Config is valid.
If no daemon is running yet, policies are read when you run 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.
6

Verify with doctor

Before connecting for the first time, let Kongtrol validate everything's in order:

bash
$ kongtrol doctor
text
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.

7

First connection

A whole group:

bash
$ kongtrol up --group work
[+] office      connected
[+] dev-server  connected
[+] aws         connected

Several profiles without a group:

bash
$ 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:

bash
$ kongtrol up office
$ kongtrol up us-content

Kongtrol keeps running in the background: closing the view disconnects nothing. When you're done:

bash
# 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:

bash
$ 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
8

Web dashboard

bash
$ 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:

PageWhat it does
OverviewLive tunnels, per-tunnel traffic charts, active routes, policy resolver, group quick-launch, connect/disconnect all
StudioTabs: routing policies (CRUD + rule tester), VPN profiles (CRUD, config + keychain), and groups (CRUD + connect/disconnect)
SecurityLive 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 LogAudit events filterable by profile/level, with an HMAC-signed indicator
SettingsHealth check, scheduler + rules, split DNS, kill switch/DNS guard tuning, public IP services, audit log
bash
# 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=
The dashboard is compiled into the binary — nothing extra to install. It's full management now (create/edit profiles, policies, groups, toggle the kill switch live), not just read-only monitoring. The dashboard's own port/bind is still CLI-only (kongtrol config dashboard set-port <port>) — changing it from the page serving the request would break the connection.
9

Daily usage

CommandWhat it does
kongtrol up --group workStart the day (office + dev-server + aws)
kongtrol down --group workEnd the day
kongtrol up us-contentNetflix, Hulu, Claude AI...
kongtrol down --allShut everything down
kongtrol statusSee what's connected
kongtrol status --watchLive monitoring (2s)
kongtrol status --watch --dashboardLive monitoring + starts the embedded dashboard at the same time
kongtrol checkLook up your public IP and test for leaks now (if you turned the lookup on)
kongtrol dashboardOpen the web UI
kongtrol doctorFull diagnostics
kongtrol exportExport config without passwords (to share)

Optional time-based scheduler:

yaml
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:

yaml
vpns:
  office:
    kill_switch: true
  us-content:
    kill_switch: false

Update a password:

bash
$ 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.

ConnectionWhat it does
kongtrol up [profile...] [flags] --all --dry-run --fav --group groupConnect one or more VPN profiles (or all with --all)
kongtrol down [profile...] [flags] --all --group groupDisconnect one or more VPN profiles (or a group with --group)
kongtrol status [flags] --dashboard -w, --watchShow 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
SetupWhat 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 profileApply 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
DiagnosticsWhat it does
kongtrol doctor [flags] --fixCheck 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 NShow Kongtrol's events
SystemWhat 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 flagsWhat it does
--alert-bellring bell on critical alerts
-c, --config pathconfig file path (default: ~/.kongtrol/kongtrol.yaml)
-h, --helphelp for kongtrol
--jsonemit JSON output for automation
--plainplain ASCII output (no color and no Unicode symbols)
-q, --quietreduce non-essential output (no banner/spinner)
10

Troubleshooting

DNS not restored after a crash:

bash
$ sudo cp /etc/resolv.conf.kongtrol.bak /etc/resolv.conf

Kill switch still active with no internet after disconnecting:

bash
$ 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.

bash
$ sudo iptables -F OUTPUT

The VPN client isn't showing up in auto-detection:

bash
# 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":

bash
$ warp-cli register

Wrong or expired password:

bash
$ kongtrol init
# Select the profile → "Refresh credentials" → enter the new one
If a session/token/credential failure is detected during connect/reconnect, Kongtrol raises a re-auth required alert with an adapter-specific hint.

File layout:

text
~/.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