KERNOVIQ runs on a Windows server or PC in its own Linux distribution in the Windows Subsystem for Linux (WSL 2). The setup program puts everything in place; users on the network then reach KERNOVIQ through this computer over HTTPS, exactly as they would reach a Linux server. The product, its data and its backups are the same as on Linux (install.md, airgap.md).
In Turkish: Windows’ta KERNOVIQ.
users' browsers ──HTTPS :443──▶ Windows: KernoviqProxy service (Caddy)
│ 127.0.0.1:8280 (WSL localhost forwarding)
▼
WSL 2: distribution "KERNOVIQ" (Ubuntu 24.04, systemd)
Docker Engine ─ KERNOVIQ (web, API, workers, PostgreSQL, Valkey)
1. Requirements
| Minimum | Recommended | |
|---|---|---|
| Windows | Windows 10 22H2, Windows 11, Windows Server 2022 or 2025; 64-bit (x64) | Windows Server 2025 |
| Memory | 6 GB | 8 GB or more |
| Disk | 20 GB free on the data folder's drive | 40 GB or more, plus room for backups |
| Processor | hardware virtualization on (Intel VT-x / AMD-V; in a virtual machine: nested virtualization) | 4 cores |
| Network | TCP 443 (and 80 for the redirect) reachable from user networks; users browse to this computer's DNS name or to its IP address | a DNS name for this computer that users can resolve |
| Internet | at installation and upgrades: Microsoft (WSL), Ubuntu's archive, the KERNOVIQ site and its image registry |
Not supported: Windows Server 2019 and older, 32-bit or Arm Windows, domain controllers (install on a member server). An administrator account is needed to install.
2. Install
- Download
KERNOVIQ-Setup.exefrom the KERNOVIQ site. Before running it, check Properties → Digital Signatures: the signer is the KERNOVIQ publisher. The SHA-256 of every setup program is in the release's signedSHA256SUMS(releases/<version>/). - Run it as an administrator and accept the licence agreement.
- Settings:
- Full edition (recommended): choose the licence file holding the
key from the licence e-mail (
KQL1…); the setup fetches the full edition from the licence server with it and activates it. - Trial: without a licence (the trial edition). A licence key entered later in Settings → Licence moves it to the full edition in place.
- Either way users on the network connect over HTTPS, at the server name
(default: this computer's DNS name) or at this computer's IP address
(
https://192.168.1.20). To keep KERNOVIQ to this computer instead (http://127.0.0.1:8280, nobody else can connect), install from the command line withkernoviq install --local. - Use my organization's certificate: a PEM certificate and its key from your CA (for example AD CS). Without it the setup creates an internal CA.
- Data folder: where the distribution's virtual disk grows (default
C:\ProgramData\KERNOVIQ\wsl; a local NTFS drive).
- Full edition (recommended): choose the licence file holding the
key from the licence e-mail (
- The setup turns on WSL if needed. If Windows must restart for that, the wizard says so; after the restart, sign in with the same account and the installation continues by itself in a window.
- The first installation takes 10–20 minutes (Ubuntu, Docker Engine and the
KERNOVIQ images are downloaded). At the end the wizard shows:
- the address, e.g.
https://kernoviq.example.internal; - a one-time link to create the organization and the first
administrator in the browser; keep it to yourself until it is used, then
retire it:
kernoviq ctl config set SETUP_TOKEN=andkernoviq restart(kernoviq statusreminds you while it is set); - with the internal CA:
C:\ProgramData\KERNOVIQ\kernoviq-ca.crt, which users' computers must trust (section 4); - the backup key
C:\ProgramData\KERNOVIQ\keys\backup.key: copy it to a safe place outside this computer; backups cannot be restored without it.
- the address, e.g.
The Start menu gets a KERNOVIQ shortcut to the address, and the
kernoviq command works in every new administrator's command prompt or
PowerShell window.
Unattended installation
KERNOVIQ-Setup-<version>.exe /S /ACCEPT_EULA /SERVERNAME=kernoviq.example.internal /LICENSEKEYFILE=C:\licence.txt
| Option | |
|---|---|
/S |
silent (upper case, on its own) |
/ACCEPT_EULA |
required with /S: you accept the End-User Licence Agreement |
/EDITION=full or demo |
the full edition (default) or the trial; both serve the network |
/SERVERNAME=name |
the DNS name users browse to (they can also use the IP address) |
/LICENSEKEYFILE=file |
the licence key (required for the full edition) |
/CERT=file /KEY=file [/CA=file] |
your organization's certificate (PEM) |
/DATADIR=folder |
the data folder |
Exit codes: 0 installed, 3010 Windows must restart (the installation
continues after the next sign-in of the same administrator), 1 failed (see
the logs, section 9), 2 cancelled or /ACCEPT_EULA missing.
The setup program runs the installation engine, which administrators can also
run directly: kernoviq help lists its options (ports, --local,
--allowed-cidrs, --firewall-public, local copies of the WSL package and the
Ubuntu image).
3. What the installation sets up
| Part | What it is |
|---|---|
C:\Program Files\KERNOVIQ |
the program: kernoviq.ps1 (engine and commands), bin\kernoviq.cmd (on the system PATH), the proxy (proxy\caddy.exe), licence texts, uninstall.exe |
C:\ProgramData\KERNOVIQ |
config.json, logs\, backups\, keys\backup.key, kernoviq-ca.crt, the proxy's configuration and certificate (proxy\), the distribution's disk (wsl\) |
| WSL distribution KERNOVIQ | Ubuntu 24.04 (Canonical's image, checked against its pinned SHA-256) with systemd, Docker Engine and Compose v2 from Ubuntu's archive and automatic security updates. No access to Windows programs or Windows drives. KERNOVIQ lives in /opt/kernoviq and is operated with kernoviqctl as on Linux |
| account kernoviq-wsl | a local account that owns the distribution. Its random password is known only to Task Scheduler and never expires; it may only run scheduled tasks — signing in locally, over Remote Desktop or over the network is denied — and it is hidden from the sign-in screen |
task \KERNOVIQ\Distribution |
at Windows startup, without anyone signed in: keeps the distribution running and starts it again if it stops; copies new backups out once an hour |
task \KERNOVIQ\Run |
carries out administrators' kernoviq commands inside the distribution |
| service KernoviqProxy | Caddy as the virtual account NT SERVICE\KernoviqProxy: HTTPS on 443 (TLS 1.2 and 1.3), a redirect from 80, a "starting" page while KERNOVIQ starts after a restart; the server name and this computer's IP addresses are served, other host names are sent to the server name. It forwards to 127.0.0.1:8280, which only this computer can reach |
| firewall rules (group KERNOVIQ) | inbound 443 and 80 for the proxy service only, on Domain and Private networks (--firewall-public adds Public) |
| WSL settings | the service account's .wslconfig: memory for the WSL virtual machine (three quarters of the computer's, between 4 and 16 GB, leaving 2 GB to Windows; kernoviq memory GB changes it) |
| Application event log | source KERNOVIQ: installation, upgrades, and a warning (event 1001) when the distribution keeps stopping |
Installed with --local (this computer only), there is no proxy service and no
firewall rule: KERNOVIQ answers at http://127.0.0.1:8280 on this computer. So
do trial installations made before the trial served the network; they keep
that on upgrades.
4. Users and the network
- Name or address: users browse to the server name, which must resolve to
this computer (an A record in your DNS), or to this computer's IP address.
The certificate is issued for that name and for this computer's IPv4
addresses; other names are redirected to the server name. When the address
changes (DHCP),
kernoviq cert renewadds the new one. - Internal CA: distribute
C:\ProgramData\KERNOVIQ\kernoviq-ca.crtto the users' computers, for example by group policy (Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies → Trusted Root Certification Authorities).kernoviq ca --trustalso trusts it on this computer. - Your own certificate later:
kernoviq cert install --cert FILE --key FILE [--ca FILE](PEM, leaf first). The internal CA's server certificate is renewed withkernoviq cert renew;kernoviq doctorwarns 30 days before it expires. - Firewall: the rules apply to Domain and Private networks. On a network
Windows treats as Public, users cannot connect: classify the network as
Private, or install with
--firewall-public. - Internal systems (directory, mail relay, webhooks, scan targets in
private ranges):
--allowed-cidrsat installation, orkernoviq ctlas in airgap.md section 8.
5. Daily operation
Run these in an administrator's command prompt or PowerShell window:
| Command | |
|---|---|
kernoviq status |
what runs, and whether KERNOVIQ answers |
kernoviq doctor |
checks Windows, WSL, the distribution, the proxy, the certificate, DNS, the firewall and the backups, with advice |
kernoviq start, stop, restart |
the whole application; restart web (one service) |
kernoviq logs [-f] [SERVICE] |
the application's logs |
kernoviq backup |
an encrypted backup now |
kernoviq restore FILE [--force] |
replace all data with a backup (a backup of the current state is made first) |
kernoviq cert show, renew, install |
the server certificate |
kernoviq ca [--trust | --untrust] |
the internal CA certificate |
kernoviq proxy reload |
write the proxy's configuration again and restart it |
kernoviq memory [GB] |
memory of the WSL virtual machine (restarts KERNOVIQ) |
kernoviq ctl ARGS… |
kernoviqctl inside the distribution, for everything else (airgap.md) |
kernoviq upgrade, uninstall, version, help |
After Windows restarts, KERNOVIQ is back within a few minutes without anyone signing in; until then users see the "starting" page.
6. Backups
KERNOVIQ makes an encrypted backup every night inside the distribution, and
before every upgrade. Once an hour new backups are copied to
C:\ProgramData\KERNOVIQ\backups: include that folder in your Windows backup.
Copies older than 45 days are removed while at least 7 newer ones remain.
The backups are encrypted with the backup key
(C:\ProgramData\KERNOVIQ\keys\backup.key, readable by administrators only).
Keep a copy of it outside this computer. To restore:
kernoviq restore C:\ProgramData\KERNOVIQ\backups\kernoviq-<date>-<label>.kqbak
Uninstalling keeps the backups and the key. A new installation on the same
computer takes that key over before it makes a backup of its own, so the
earlier backups can be restored into it. A different key found there is kept
as backup-<date>.key, never deleted. To restore on another computer, copy
the key to C:\ProgramData\KERNOVIQ\keys\backup.key there before installing
KERNOVIQ, then restore the backup into the new installation.
7. Upgrades
Run the newer setup program. It makes a backup, upgrades the distribution and
KERNOVIQ, and rolls back to the previous release by itself if the upgrade
fails; settings, data and certificates stay. It keeps the build the
installation runs: the full edition (also one moved there from the trial) is
fetched from the licence server with the licence key it has activated, so the
key must cover the new release (licensing.md, "Updates").
To move a trial installation to the full edition by hand: kernoviq ctl upgrade-edition. Running the same version again
repairs the Windows side (account, tasks, proxy, PATH). Unattended:
KERNOVIQ-Setup-<version>.exe /S /ACCEPT_EULA.
If WSL itself needs an update that requires a restart, the setup says so (exit
code 3010): restart Windows and run the setup program again.
8. Uninstall
Settings → Apps → KERNOVIQ → Uninstall (or uninstall.exe in the program
folder). It makes a final backup, then removes the proxy service, the firewall
rules, the distribution and its disk, the tasks, the service account and its
profile, and the program folder. The backups and the backup key stay in
C:\ProgramData\KERNOVIQ; tick Also delete all data, the backups and the
backup key to remove them too.
Unattended: "C:\Program Files\KERNOVIQ\uninstall.exe" /S (keeps the backups)
or /S /PURGE (deletes everything). Exit codes: 0 removed, 1 failed, 2
cancelled. WSL itself stays installed: other software may use it.
9. Troubleshooting
Logs: C:\ProgramData\KERNOVIQ\logs — install-*.log, upgrade-*.log,
uninstall-*.log, distribution.log (the keepalive task), run.log (the
request task), proxy.log. Windows' Event Viewer → Applications shows the
events of the source KERNOVIQ. kernoviq doctor points at most problems.
| Symptom | Cause and fix |
|---|---|
hardware virtualization is off |
turn on Intel VT-x / AMD-V in the firmware; in a Hyper-V virtual machine: Set-VMProcessor -VMName NAME -ExposeVirtualizationExtensions $true (VMware: "Expose hardware assisted virtualization") |
cannot run WSL 2 as KERNOVIQ needs it |
update Windows to 10 22H2, 11, or Server 2022 or newer |
this computer is a domain controller |
install on a member server |
TCP port 443 is already in use |
another web server (IIS) holds it: stop that site, or install with --https-port |
| users get a certificate warning | their computers do not trust the internal CA yet (section 4), or they use a name the certificate does not carry: use the server name |
curl.exe on Windows: CERT_TRUST_REVOCATION_STATUS_UNKNOWN |
the internal CA publishes no revocation list, and Windows' curl insists on one; browsers do not: add --ssl-no-revoke (scripts and monitoring) |
| users cannot connect at all | DNS does not point to this computer, or the network is Public for Windows (section 4); kernoviq doctor checks both |
| the "starting" page stays | the distribution does not come up: kernoviq doctor, distribution.log; event 1001 means it keeps stopping |
| the setup failed | the reason is in the wizard's details and in install-*.log; fix it and run the setup program again: it continues with what is already done |
| PowerShell refuses the scripts | group policy requires signed scripts (AllSigned): KERNOVIQ's scripts are signed, so add the publisher's certificate to the computer's Trusted Publishers |
10. Security notes
- The distribution cannot start Windows programs and sees no Windows drives; files move between Windows and it only through the request task, as the service account.
- Only the proxy service listens on the network. KERNOVIQ's own port 8280 is
bound to
127.0.0.1; PostgreSQL, Valkey and the API are not published outside the distribution. - The backup key, the proxy's private key and the configuration are readable by administrators and SYSTEM only; the service account can only change the folders it works in.
- The setup program, the uninstaller and the PowerShell scripts are signed with the publisher's code-signing certificate; the downloads the installation makes (WSL, Ubuntu, Caddy, KERNOVIQ) are checked against pinned checksums or the release signature.
- KERNOVIQ sends no telemetry from Windows either.