Case Files

On first boot you reach the Kodachi-branded LightDM login (default credentials kodachi / Security4All; use the greeter's keyboard/language selector first if needed), then the dark XFCE desktop loads with the Conky real-time system monitor. The Kodachi Dashboard then auto-launches and shows a welcome screen for terms acceptance, dashboard mode selection (Circle, Lite Classic, Vitals, SOC or ColonyOps), optional startup privacy settings and network detection, and it offers AutoShield as the guided first-boot setup route. Automatic first-boot operations include binary deployment verification, DNSCrypt auto-configuration, online authentication, system status collection and Conky initialization. AutoShield is the Dashboard's countdown-driven setup wizard, not a separately launched program.

Yes. Every Kodachi security service is a standalone CLI-first Rust binary, so the full suite works headless with no dashboard. The Kodachi Terminal Server edition is terminal-only by design (no GUI at all), built for hardened servers and headless deployments, and exposes the same binaries (health-control, tor-switch, dns-switch, routing-switch, workflow-manager, and more) directly from the command line.

Yes. On the desktop edition the "Kodachi Rofi Actions" menu gives keyboard-driven access to security operations, network controls, services, and utilities without using the mouse. The launcher is bound to Ctrl+K (it runs /usr/local/bin/kodachi-rofi-actions). The broader application/rofi launcher is also bound to Super+R, Alt+F1, Alt+F3, Ctrl+Escape, and a tap of the left Super key. On the Terminal edition everything is driven from the shell.

It is a set of keyboard-driven Rofi menus installed to /usr/local/lib/kodachi-rofi/. The Actions menu is the primary dispatcher and opens sub-menus: Favorites (quick-launch tools), Network (VPN connect/disconnect, Tor toggle, DNS switching, routing mode), Services (start/stop/status for Tor, DNSCrypt, firewall), and Utilities (cleanup, MAC randomization, hostname change, panic triggers). Launch it with Ctrl+K.

Yes. On first login the AutoShield welcome script detects whether DNSCrypt has been configured (via a marker file), and if not it auto-configures encrypted DNS, retrying up to 3 times with short delays. It writes a marker so it does not reconfigure on later logins, and it auto-recovers if systemd-resolved hijacks DNS. You can force reconfiguration with:

Yes. Kodachi delivers a fully prepared, hardened environment with built-in privacy tools ready from the very first boot. On the Desktop edition the Kodachi Dashboard auto-launches at login and presents AutoShield, its guided first-boot wizard, which runs a multi-step security hardening sequence; you can re-open it any time from the dashboard header. Only three AutoShield steps are on by default (Authenticate, Randomize Hostname, Randomize Timezone); VPN, DNS mode and Torrify wait until you turn them on. The overview describes Kodachi as providing out of the box what would take most users months of setup to build correctly.

Yes. Kodachi ships KAICS (an 8-binary plain-English CLI) and an ai-gateway for policy-firewalled agent execution. It exposes 9 named engine paths: TF-IDF, ONNX intent classifier, ONNX semantic, Mistral.rs, GenAI/Ollama, legacy local LLM, Claude CLI, Codex CLI, and OpenCode. Local engines run on-device; a configured external provider can receive prompts and context even when its traffic uses VPN or Tor. On Desktop, the AI Chat button is available in the Circle and Lite Classic dashboards to explain commands or suggest sequences without leaving your tab.

Kodachi provides 25 auto-documented, command-bearing Rust binaries registered as 26 CLI services, plus bundled companion runtimes, covering routing, Tor, DNS, integrity, host security monitoring, health/emergency control, authentication and a local AI stack. On Desktop the Kodachi dashboard orchestrates 606 generated commands with no GUI freezing. The Terminal edition ships the same 29 signed binary files in /opt/kodachi/dashboard/hooks/ (21 core + 8 AI); with the signed host-exposure-defaults.json policy file, the trust set contains 30 signed artifacts. The Conky telemetry display itself is a Desktop add-on.

No. Kodachi is a hardened privacy and security operating system, not a standalone VPN provider. A VPN is only one component; Kodachi also bundles Tor routing, DNS leak protection, anti-forensics tools, multiple tunneling protocols, and hardened defaults. The docs explicitly say it should not be compared to a normal VPN subscription because it is an integrated OS-level stack rather than a single tunnel service.

Kodachi is a Debian 13-based distribution shipping multiple VPN protocols and explicit route recovery controls, Tor routing, DNS protection, encrypted crypto wallets, full-disk encryption utilities, a hardened browser, and an integrated dashboard, all working from first boot. The stated value is delivering out of the box what would otherwise take most users months of manual setup and trial-and-error to assemble and harden correctly.

Choose Desktop (full XFCE on Debian 13, ~4.2GB) for daily privacy-focused computing with a GUI. Choose Terminal (minimal live ISO, ~3GB, Debian 13) for testing the toolchain, headless privacy deployments, or running a dedicated SOCKS proxy gateway on old hardware or a VM. Choose the Binary Suite to run the signed Rust binaries on an existing Debian-based system. All are free for personal and other non-commercial use and share the same underlying privacy stack.

Use a non-persistent live USB or a VM such as VMware, VirtualBox, or QEMU. Live mode does not save session changes to the live medium by default, and local disks are not intentionally mounted or written unless you or a tool does so. A VM adds an isolation boundary but is not zero-risk, especially with shared folders, passed-through devices, or bridged networking. Take a VM snapshot before experimenting so you can roll back.

If you are new, start inside a virtual machine rather than on bare metal. Boot one VM from the live ISO and, if useful, install another into its own virtual disk. Take a VM snapshot before experimenting so you can roll back. This reduces risk to the host, but it is not zero-risk: hypervisor defects and enabled shared folders, device passthrough, clipboard integration, or bridged networking can cross the isolation boundary. Install on a physical drive only if you need Kodachi as a daily-driver OS. See safe testing boundaries and supported run methods.

Kodachi's system scripts and configuration are published under the Kodachi Source-Available Noncommercial License v1.1 (KSAN-1.1) and can be read and audited subject to that license; the Kodachi-authored binaries are closed and ship as signed builds. The 29 signed binary files, ISO, and binary tarball are cryptographically signed with a published public key. The currently published signed warrant canary is dated 2026-11-05. Kodachi is built by a named maintainer, Warith Al Maawali (digi77.com), the same person since 2013, and is independently tracked on DistroWatch.

Kodachi is provided for legitimate privacy protection, security research, and educational purposes only and must not be used for illegal or criminal activities. Users are solely responsible for compliance with all applicable laws in their jurisdiction, and the developers disclaim all liability for misuse. Anyone intending unlawful use is told to discontinue use immediately.

No tool guarantees absolute anonymity. Kodachi gives a strong integrated stack (VPN, Tor, proxies, DNS controls, anti-leak enforcement) and hardened defaults from first boot, but real anonymity still depends on your configuration and behavior - which routing mode you select and your OPSEC. The docs frame it as giving real control and protection and teaching better habits, not as automatic, absolute anonymity. The Known Limitations page lists what Kodachi does not protect against and which protections stay off until you turn them on.

No. The free tier uses the same binaries, the same OS-level hardened stack, and the same updates as the paid plans. The differences are backend infrastructure quality, commercial usage rights, priority issue triage, plus the Vitals system monitor, the top-level SOC dashboard, the ColonyOps operations workspace, the Advanced startup launcher and the VPN Providers and Mobile Manager pages in Lite Classic, which the same binary unlocks with a license; never the privacy and protection core or its security capabilities.

Kodachi does not require conventional account fields such as your name, email, or phone number for authentication. That is different from collecting no data. Service operation processes a derived device identifier, session and client-version data, and network metadata such as current or previous IP addresses for authentication and security events. Web requests also reach Apache access logs, which the current operations code documents as rotating within hours, while service-delivery records can persist for operational purposes. These limits reduce directly identifying account data, but they do not make the service metadata-free. See also the authentication privacy boundary.

Authentication unlocks Kodachi's service-backed features: the built-in VPN nodes, proxy pool, encrypted DNS, and other cloud-assisted tools. You do not log in by hand; the dashboard signs in automatically as it loads, with no username or password to type.

It separates free from premium access and limits abuse so shared nodes remain usable. It requires no Kodachi account fields such as email, phone number, or name. That reduces directly identifying account data, but the service still processes a derived device identifier and can observe request, session, and network metadata. Authentication therefore controls access without a conventional personal account; it does not by itself prove anonymity (see is authentication tracking me).

Authentication distinguishes paid from free users, limits abuse, and protects shared infrastructure. It asks for no Kodachi account fields such as email or phone. That reduces directly identifying account data, but it does not prove anonymity: the authentication endpoint can still observe request, session, and network metadata. The OS itself runs without authorizing, but service-backed features will not fully work until authentication succeeds; it is an anti-abuse access gate, not a guarantee that no metadata exists.

In part. The system scripts and configuration are published under the Kodachi Source-Available Noncommercial License v1.1 (KSAN-1.1), rather than an OSI-approved open-source license; the Kodachi-authored binaries are closed and ship as signed builds. Published code is available at https://github.com/WMAL/kodachios. The full source of versions prior to v9 is public, including Kodachi 8.27 and the full dashboard source, and the Kodachi Bash scripts shipped in the ISO are hosted in the same repository.

Study the published code and its history on GitHub at https://github.com/WMAL/kodachios. The full source of pre-v9 releases such as Kodachi 8.27 and the complete dashboard source are there, and the project publishes source after major changes so you can trace how the system evolved across versions. The Kodachi bash scripts bundled in the ISO are also hosted in that repository, so you can read exactly what runs at boot and during setup.

Kodachi is created and maintained by Warith Al Maawali, an independent security engineer who has developed it as a one-person project under the same name since 2013. He builds it openly under his real identity rather than as an anonymous team, and also runs digi77.com. You can see who he is and follow the work directly on LinkedIn at https://om.linkedin.com/in/warith1977 and on X (Twitter) at https://x.com/warith2020, and the full project history is on GitHub at https://github.com/WMAL/kodachios.

Yes. Kodachi publishes a signed warrant canary at /tools/warrant.html. The currently published signed statement is dated 2026-11-05. There is no fixed schedule for new statements, so read the date inside the signed text to see how recent it is. Verify its OpenPGP signature and treat a statement that stays old unusually long, or any wording change, as information when assessing the canary. It is part of Kodachi's transparency model alongside the KSAN-1.1 published scripts and configuration and cryptographically signed releases.

It is a short, plain-language agreement, not data collection and not registration. Nothing is sent anywhere; accepting it only writes a local acceptance file. Its real purpose is to protect the developer, and that protection matters precisely because Kodachi is not run by an anonymous team. Most privacy projects hide behind pseudonyms. Kodachi is built openly by Warith Al Maawali under his real identity, which is exactly what lets you verify and trust who is behind it. The trade-off of using a real name is real exposure: if someone uses Kodachi to commit a crime, the author could be wrongly dragged into it. The terms make the boundary explicit. They state that Kodachi's purpose is to protect privacy, that it must not be used for illegal activity, that you should stop immediately if your intent is unlawful, that the developer disclaims all liability for any illegal actions committed by users, that you agree to use it responsibly and legally, that your own data security remains your responsibility, that the software is provided as-is with no warranties, and that the terms may be updated so you should review them. In short, the acknowledgement exists so every user understands that responsibility for how Kodachi is used rests with the user, not with the person who chose to put his real name on a privacy tool.

Linux Kodachi is now known as Kodachi OS. Older documentation, downloads, and archived material may still use the previous name, so both names still appear across older pages, articles, file names and forum posts. They refer to the same project.

Only the presentation changed. It is the same maintainer and the same project, developed continuously since 2013. Files already published, such as linux-kodachi-xfce-9.0.1-amd64.iso, keep their original names so existing checksums, signatures and download links stay valid; the new naming applies to future releases.

One screen, three choices. Kodachi 8 had one dashboard with about ten switches, and its boot script connected the VPN, Tor and DNS from a saved settings file. Kodachi 10 puts five dashboards over the whole command catalog (How many binaries and commands does Kodachi give me?), and the saved auto-connect became AutoShield, so the first screen offers far more than everyday browsing needs. You only have to touch this much:

1. Accept the terms once. On the Quick Launch screen choose Advanced and open the Advanced setup screen.
2. On its AutoShield tab enable the steps you want applied at every boot: Authenticate, your VPN (the Kodachi VPN or your own profile), DNSCrypt, and Torrify or MAC randomization if your use case calls for them. Pick a short countdown and arm it. Three steps are on by default and everything else stays off until you turn it on (Can I customize the AutoShield countdown timer and steps?). An armed AutoShield then runs once per boot whichever startup screen you keep (AutoShield at boot).
3. Launch the Circle dashboard, the beginner wheel with a bounded set of stations. Lite Classic, ColonyOps, SOC and Vitals are there for depth; nothing requires you to open them.

After that, every boot is: wait for the countdown, browse. Stay on the Kodachi Live or Persistent boot entries; the hardened tiers and the deeper dashboards exist for threat models that need them, and the docs recommend the lighter entries for everyday use (Which boot mode should I choose by default?). On a plain Live boot these choices last for the session only; to make the stick remember them, pair this with How do I make a Kodachi USB stick that keeps my settings and comes up configured on every boot?. If you have not connected to a network or signed in yet, start with getting online and signed in.

Connect to your network first, then sign in. A wired connection works as soon as the cable is in. On the Desktop edition, for Wi-Fi, click the network icon in the panel's system tray, pick your network from the list and type its Wi-Fi password, as on any Linux desktop. There is nothing to press on your router.

Once you are online, the dashboard signs in to Kodachi's service by itself when it starts, and it retries if the network is not ready yet. Until it gets through, the Auth status reads Auth status unknown: connectivity is limited. Auth check will resume when network is restored. If that does not change after you are connected, press Sign in at the bottom of the dashboard's left rail, or sign in from a terminal:

On the Terminal edition there is no tray and no dashboard. Connect to Wi-Fi with NetworkManager's text menu, or with one command that asks for the Wi-Fi password instead of keeping it in your shell history (use your network's name), then sign in with the command above:

Signing in needs no account, email address or authenticator app: it registers this device with Kodachi's service (why authentication is not tracking). Two-factor codes are an optional extra for locking the dashboard itself (dashboard authentication). Actions that answer Authentication required, such as connecting a VPN, work after this step.

If the network shows as connected but Kodachi still reports no internet, run the network recovery, then sign in again:

The login itself is kodachi with the password Security4All (default credentials). For what to set up next, see the shortest path to a configured system.

Kodachi supports both legacy BIOS and UEFI - the documented boot support is 'BIOS + UEFI + Secure Boot'. UEFI Secure Boot is supported through signed GRUB and shim packages that are bundled in the ISO, so the bootloader integrity is verified before execution and no internet download is needed during installation. For Secure Boot systems, the dedicated Kodachi Kernel Lockdown (confidentiality) entry enforces module signing and lockdown policies. Either firmware type works; only the Secure Boot security-score check is skipped on BIOS-only machines (it drops out of the maximum rather than counting as a failure).

No - Kodachi ships signed GRUB and shim packages so it boots normally with UEFI Secure Boot enabled, and there is a dedicated Kernel Lockdown (confidentiality) entry for trusted boot chains. The only caveat is that with Secure Boot on, the kernel enforces module signatures, so out-of-tree add-ons whose signing key your firmware has not enrolled will not load. That covers all 37 DKMS modules Kodachi ships: the AmneziaWG transport, Tirdad, and the Broadcom and Realtek Wi-Fi drivers. If you specifically need one of those, disable Secure Boot in your firmware settings and boot Kodachi Live, Persistent, Encrypted Persistence, CPU Hardened, or DMA Protection, or sign the module with a key of your own (signing Tirdad). An installed system that shows a security violation once Secure Boot is on needs its boot chain checked (the fix).

Yes. Kodachi Desktop includes a Debug Collector that gathers system diagnostics (boot logs, hardware specs, network configuration, Kodachi service status, and more) into a single zip on your Desktop. Run it interactively with:

Or skip the category menu and collect everything with:

The output is saved as ~/Desktop/kodachi-debug-*.zip.

The Debug Collector does not capture browsing data or personal files. Passwords, passphrases, keys and VPN credentials are stripped. WiFi network names (SSIDs), MAC addresses, disk-encryption (LUKS) identifiers and the system machine ID are replaced with placeholders. Public IP addresses are redacted; private LAN, loopback and link-local addresses are kept, because a network problem cannot be diagnosed without them. You can also deselect specific categories from the interactive menu before collection starts if you want to exclude anything else. After it produces ~/Desktop/kodachi-debug-*.zip, upload that file to your preferred file-sharing service and share the link with the support team on Discord (https://discord.gg/KEFErEx) or via the contact form at /docs/support.html.

Yes. You never need to reinstall the OS to update binaries. First stop the Permission Guard daemon so it does not cause file-permission conflicts during the update:

or:

Then verify it is stopped with:

or:

Then run the binary installer with no sudo:

Followed by the dependencies installer with sudo:

And finally confirm with:

On an installed Kodachi ISO, where the binaries come from apt, update through apt or the Repository Manager's Update all instead: see Can I update Kodachi without downloading a new ISO?

Permission Guard is a runtime daemon that monitors and enforces file permissions, so if it is running while the installer overwrites binaries it can cause file-permission conflicts during the update. The simplest documented approach is to log out, run the update scripts, then log back in; alternatively stop the daemon explicitly with:

or:

And confirm it is down with:

If you installed to a custom path, call the binary at that path instead of the default /opt/kodachi/dashboard/hooks/permission-guard, for example:

See the binary version with:

Or, for a quick single-binary check:

After updating, the documented verification step is:

And you can also verify integrity, signatures, and version together with:

Note that automatic updates are planned for future releases; for now updates are manual via the binary and dependency installer scripts.

Yes. Supported methods are: Live USB, which boots without installation and does not persist session changes to the live medium by default; Persistent Storage, which saves selected configuration; Bare Metal installation; and a Virtual Machine for testing or isolation. Live mode does not guarantee that every disk stays untouched: local or removable disks can be written if you or a tool mounts and uses them. Kodachi binaries can also run inside Docker. Documented USB writers include Ventoy, Rufus, and balenaEtcher.

Yes. Kodachi follows the Parrot OS pattern: network is disabled during installation in all preseed files, UEFI Secure Boot packages are bundled in the ISO, and the text installer is fully unattended with no network, locale or keyboard prompts. This means faster, reliable, offline installation that works in isolated or air-gapped environments. Network is configured automatically on first boot afterwards.

By design. The GRUB-launched text installer deliberately disables the keyboard-layout prompt and defaults to US English so the install is fully unattended and offline-capable - all keyboard layouts are still included on the ISO, and you can switch to your layout at any time after installation with no issues. If you want to pick your layout and locale during installation, boot into the live desktop and use the Calamares graphical installer instead, which exposes those options.

Yes. The Kodachi binaries can be installed standalone on an existing Debian-based system (default install path /opt/kodachi/dashboard/hooks) and even run inside Docker/Docker Compose, which both default to /opt/kodachi/dashboard/hooks. This is useful for testing or integrating specific tools (routing-switch, dns-switch, tor-switch, etc.) into your own workflow without booting the full Kodachi OS.

Use the Debian text installer from the ISO GRUB menu, not the Calamares GUI encrypted path. Boot the ISO, open 'Advanced options & fallback modes...', and choose 'Install Kodachi (Text + Full Disk Encryption, Boot-Nuke Compatible)' or the equivalent unattended encrypted entry. These keep /boot outside LUKS so the passphrase prompt stays in initramfs, which cryptsetup-nuke-password requires. Calamares is fine for standard installs but its encrypted path can put the first LUKS prompt in GRUB, which blocks boot-nuke.

This is intentional Parrot-style behavior: the text installer launched from the GRUB menu disables keyboard, locale, and network prompts so installation is fully unattended, fast, and works offline/air-gapped with no DHCP dependency. The keyboard defaults to US English during setup only (preseed sets xkb-keymap us, netcfg/enable false); all layouts ship in the system and you switch after first boot. To choose layout/locale during install, use the Calamares graphical installer from the live session instead.

The VM is using a non-US keyboard layout (often UK), which swaps @ and ". Fix it at the hypervisor: for QEMU CLI add '-k en-us'; in virt-manager set the Display Spice/VNC keyboard layout to English (US); in VirtualBox use Settings > General > Advanced > English (US) or 'VBoxManage modifyvm "Kodachi VM" --keyboard-layout "English (US)"'.

VirtualBox does not enable EFI by default, so a UEFI boot fails unless you turn it on. In the VM settings enable EFI, allocate 4GB+ RAM, set the network to NAT or Bridged, and attach the ISO to the virtual optical drive. If issues persist, use a BIOS boot or the Advanced menu hardware-fallback entries (nomodeset, noapic, GPU compatibility).

The ISO is BIOS + UEFI compatible and ships signed GRUB and shim, so Secure Boot is supported. If a strict Secure Boot system refuses other entries, pick the 'Kodachi Kernel Lockdown (confidentiality)' entry, which uses signed modules (module.sig_enforce=1) and lockdown=confidentiality designed for Secure Boot enforcement. For display/hardware boot failures, use 'Advanced options & fallback modes...' which offers nomodeset, noapic, legacy NIC naming, and GPU compatibility modes.

This is usually a bad or wrong USB write. The recommended method on Linux is dd:

Confirm the device with lsblk first because dd overwrites the whole target drive. On Windows use Rufus or Etcher, and always verify the ISO checksum before writing so you don't flash a corrupted image.

A mismatch means the file is corrupted or incomplete (interrupted download or bad USB write) or, rarely, tampered with, so do not install it. Re-download from the official Kodachi download page and re-check the hash, or use the browser-based File Verification tool, which checks against all official Kodachi checksums automatically and also checks the image's signature when you add its .sig file. Only proceed once the hash matches exactly.

If one published checksum disagrees while the others match (for example the SHA-512 is off but SHA-256 and MD5 match), the published value is the likely culprit, usually because the page had not caught up with a freshly uploaded image. Compare against the checksum files themselves: on the download page, each image's Files & checksums list offers its .sha256 and .sha512 files for download. Verify the signature as above, and tell us in the Discord support channel so the value gets corrected (verifying the ISO).

Yes. Stop the installation when any required verification fails. The detached RSA-4096 package signature, SHA-256 package checksum, and required per-binary signatures are independent checks; one passing check does not excuse another required check failing. Re-download the package and its verification files from the official mirror, verify them again, and install only after every required check passes.

The minimal Debian desktop install does not include curl while live ISOs do, and the Kodachi scripts are fetched with curl. Install it first with:

Then re-run the installer; the dependency script then pulls in the other essentials like procps and psmisc.

The install scripts download the package from the Kodachi cloud host, so they need connectivity at install time, and they cannot install from a tarball you already downloaded. Test connectivity to the Kodachi host and run the installer again once it works. Unpacking the tarball into /opt/kodachi/dashboard/hooks yourself is not a working substitute, because it skips the root-owned auth-trust setup that login depends on. For the full install steps, and how to verify a downloaded pack with no network, see What is the right way to install the Kodachi binary pack, and can it be installed without internet?

Your account simply isn't in the sudo group, which the dependency installer requires to install system packages. Switch to root with 'su -', run 'usermod -aG sudo YOURUSERNAME', exit, then log out and back in for the group change to take effect. Then run the binary installer (no sudo) and the dependency installer with sudo.

The same fix applies to a second login account on an installed Kodachi. Kodachi runs its tools without a password only for members of the sudo group, and the installer puts only the account created during the install in that group. An account you add later is not in it, so its dashboard reports 'a password is required' for every check (newer dashboards say the account is not in the sudo group and print the command for it). From an account that is in the sudo group, run:

then log out of that account and log back in. Do not write your own file in /etc/sudoers.d for it: Kodachi already grants the sudo group what the dashboard needs, and a rule written for one user name never applies to another account.

If running 'sudo visudo -c' (or any other sudo command) in a terminal seemed to make the dashboard work, that was the sudo password cache, not visudo. After you type your password, sudo remembers it in that terminal for 5 minutes (Kodachi sets timestamp_timeout=5), and a dashboard started from that same terminal borrows it. Start the dashboard from the menu, or wait 5 minutes, and the error comes back. Only the group membership fixes it for good.

The binary files lost their executable bit, usually after a manual extraction or copying without preserving permissions. Restore it with 'chmod +x /opt/kodachi/dashboard/hooks/*'. If you installed manually, make sure you ran the chmod step on all top-level files in the hooks directory.

Permission Guard is a runtime daemon that restores file permissions, so if it runs while you overwrite binaries it fights the update and causes conflicts. Stop it before updating: the simplest way is:

or:

Verify with:

Then run both update scripts and log back in. For non-default install paths, call the binary at its real location. This is by design, not a bug - Permission Guard restores correct ownership across critical Kodachi paths; for normal use leave it running and only stop it for installs/updates, restarting it afterward.

In a VM, take a snapshot before testing so you can roll back, use NAT networking for the VPN/Tor chain workflows, and expect a lower raw security score because live/VM sessions skip disk-encryption checks (not a defect). For Docker, the dependency script needs procps and psmisc plus curl/wget/openssl present first, contrib/non-free repos enabled, and debconf set noninteractive (with resolvconf linkify disabled) or the build hangs - install those in an earlier layer as the documented Dockerfile shows.

Re-authenticate cleanly:

then:

Use --relogin for long sessions. Check whether you are actually blocked with:

Note that logout also stops Permission Guard - the recommended first step before updates - so a failed-auth state is sometimes just a side effect of an interrupted update.

rsyslog was added to the Terminal package list specifically so persistent text logs survive crashes, shutdowns, and kernel issues by mirroring to /var/log/syslog. It is intentional and useful for diagnosing boot/crash problems - leave it installed; do not remove it if you want post-crash diagnostics.

No, and it does not need to. b43-fwcutter and broadcom-sta-dkms are installed, but the actual b43/b43legacy firmware blobs are already pre-extracted into the ISO at build time and shipped under /lib/firmware - so Broadcom WiFi works offline with no network fetch. The network-dependent firmware-b43-installer packages were deliberately excluded and replaced with empty dummy packages so the offline ISO build does not break.

Use Kodachi's browser-based File Verification tool at /docs/security/file-verify.html. It computes the hash locally in your browser and compares it against the official published checksums, and can also verify a .sig signature - nothing about your file is uploaded. The same tool works for individual binaries and the binary tarball, not just the ISO.

Yes. The Rust binaries are production-validated on Debian 12 (Bookworm), Debian 13 (Trixie) and Ubuntu 22.04+, and because they are highly portable they also run on most other modern Linux distributions. Any difficulty is almost always a missing system package dependency rather than the binaries themselves - deps-checker identifies and installs what's needed.

Both editions use username kodachi with password Security4All. The kodachi account has passwordless sudo, while direct root login is disabled and does not use this password. Change the password after installing for any persistent or installed system.

Yes, for the Kodachi programs and the system packages. On an installed system these two commands bring the Kodachi binaries, the dashboard and the Debian packages up to date in place:

Use full-upgrade rather than a plain upgrade: a plain upgrade holds back updates whose dependencies changed. On the desktop the Repository Manager's Update all does the same (the Repository Manager and its channels). The Kodachi binaries ship in the kodachi-hooks-core, kodachi-ai and kodachi-dashboard packages, so an update brings every fix released in those packages on your channel. The older panel launchers Kodachi Deps Update and Kodachi System Update were folded into the Repository Manager.

Some changes live in the system image rather than in a package, such as the Live stick's boot menu, system presets and the bundled browser profile, and an update does not re-apply those. Some boot fixes for installed systems do arrive with the core packages, such as the fallback boot configuration in the grub> prompt answer. For the image-level changes, and for a fresh install, a Live stick or an installation that is many releases old, install the new ISO. On a Live boot an update lasts only until you reboot, because the live system starts from the image every time, unless you boot a persistent stick (a stick that keeps its settings).

New releases and fixes are listed in the changelog and announced in the Kodachi Discord. For the binary pack's own installer, used where the Kodachi apt repository is not set up, see Can I update the Kodachi binaries without reinstalling the OS?

Yes, so back up first. A non-persistent live session does not save changes to the live medium by default, but disks that you or a tool mounts remain writable. When you choose to install Kodachi with Calamares or the text Full Disk Encryption installer, the selected target is formatted and its existing data is erased; a full-disk-encryption installation can replace the entire disk. Copy important data elsewhere before installation. See Backup & Restore, the boot-time LUKS nuke installer choice, and safe testing boundaries.

Use Kodachi's built-in Backup & Restore tool (kodachi-backup), available on both the Desktop and Terminal editions. It makes an encrypted, versioned backup of your personal data with restic. On the Desktop edition open Settings and select the Backup tab; on the Terminal edition run:

LUKS, VeraCrypt/TrueCrypt, and other dm-crypt volumes are detected automatically; by default unrecognised (unencrypted) drives are refused, but you can opt in via "Allow unencrypted destination" in the GUI or --allow-unencrypted on the CLI (restic still encrypts the backup with your passphrase, only the drive's full-disk-encryption layer is absent). The repository passphrase is never stored. It backs up your DATA only (Documents, Downloads, Pictures, Videos, Music, Desktop, Public, Templates, plus ~/.gnupg, ~/.ssh, password stores and the LibreWolf profile) and deliberately excludes desktop and system configuration (~/.config, ~/.cache, ~/.local, ~/.kde), so restoring onto the newer ISO can never break the fresh desktop. You can also back up custom folders and crypto wallets: use the Add custom folder control in the Backup tab, or on the CLI:

Monero, Bitcoin Core, Electrum, and Wasabi wallets are auto-detected and listed when present on disk. After installing the new ISO, open Backup & Restore, or run:

Your files are extracted into a ~/Restored-<date> staging folder by default, leaving the new system untouched.

Yes. Once the Kodachi apt repository is configured:

Each bundled privacy tool is then its own package and installs on its own, for example:

The same works for kodachi-hysteria, kodachi-mieru, kodachi-v2ray, kodachi-v2ray-plugin, kodachi-kloak and kodachi-dnscrypt. These carry no Kodachi dependency (only the C library), so they are standalone and even work on a plain Debian or Ubuntu box. The full install already pulls them all in, so install a single tool by name only when you want just that one:

The one exception is kodachi-pihole, which also pulls the Kodachi core, because it uses the shared setup step to configure Pi-hole on port 5353 alongside DNSCrypt.

With Secure Boot on, the kernel enforces module signatures and refuses every out-of-tree driver whose signing key your firmware has not enrolled. Kodachi ships 37 such DKMS drivers, and the Wi-Fi ones are the drivers most users notice: wl (Broadcom STA), 8814au, and 33 rtw_* modules covering Realtek USB and PCIe adapters such as the 8812au, 8821cu, 8822bu and 8723du chipsets. They are all signed, but with a certificate that is generated during the Kodachi build and is trusted by no machine, so the kernel reports signature and/or required key missing and the adapter never appears. Drivers built into the Debian kernel (iwlwifi, ath9k, ath10k, rtw88, r8169 and the rest) are signed by Debian and keep working normally, so most laptops with Intel or Atheros wireless are unaffected. You have three options: use an adapter that an in-tree driver supports, turn Secure Boot off in firmware, or, on an installed system, generate your own signing key, sign the modules with it and enrol that key with mokutil. Do not enrol the key that ships in the image - see the Security folder for why that is unsafe. To confirm this is what you are hitting, run:

and:

The binary pack, kodachi-binaries-v<version>.tar.gz, is installed by the Kodachi installer script rather than unpacked by hand: the script downloads the pack, verifies it and sets up the protected files that login depends on. If you want to look inside first, the pack unpacks to one folder holding binaries/, signatures/, config/, binaries-update-scripts/ (the installer and dependency scripts), licenses/, models/, conky/, icons/, sounds/, flags/, fonts/, others/, dnscrypt-cache/, empty_dirs/ and the metadata files MANIFEST.json, VERSION, CHECKSUMS.sha256 and generated_hashes-v<version>.json. MANIFEST.json in that folder lists every binary and what each folder is for.

On an installed Kodachi ISO, do not use the tarball. If the package kodachi-hooks-core is installed, your binaries come from apt and the installer script stops on purpose when you run it without --path. Check with:

If it reports Status: install ok installed, update with these two commands instead:

On any other Debian or Ubuntu system, use the installer script. Run every step as your normal user: the binary installer refuses to run as root and asks for sudo by itself when it needs it. If you are updating an existing install, stop Permission Guard first as described in Can I update the Kodachi binaries without reinstalling the OS?

1. Download the installer:
   curl -fsSLO https://kodachi.cloud/apps/os/install/kodachi-binary-install.sh
2. Read it before you run it:
   less kodachi-binary-install.sh
3. List its options:
   bash kodachi-binary-install.sh --help
4. Run it:
   bash kodachi-binary-install.sh
5. Install the system dependencies (this step needs sudo):
   curl -sSL https://kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash
6. Open a new terminal, so the PATH line the installer added to ~/.bashrc takes effect, and confirm the installed version:
   integrity-check check-version

The installer options are --path PATH (install to a folder you choose), --desktop (install to ~/Desktop/dashboard/hooks), --version VER (install a specific release) and --skip-path (leave ~/.bashrc alone). The default location is /opt/kodachi/dashboard/hooks. On every run it downloads the pack, checks its SHA-256 checksum, checks its RSA-4096 signature with openssl, refuses an archive containing absolute or ../ paths, and installs the binaries. Only an install to the default location also gets the root-owned auth-trust folder (the public key plus one signature per binary) that online-auth reads before it lets you log in. A --path or --desktop install does not get it, so keep the default location if you want online-auth and the dashboard login to work.

A fully offline install is not supported. The installer has no option to use a tarball you already have, it always downloads its own copy, and the dependency installer installs system packages with apt. The machine needs internet while you install. What you can do offline is verify the pack yourself. On a machine with internet, in an empty folder, download the pack and its three verification files:

1. Download the current pack:
   curl -fLOJ "https://kodachi.cloud/downloads/download.php?f=binaries-tarball"
2. Read the version from the file name:
   V=$(ls kodachi-binaries-v*.tar.gz | sed 's/^kodachi-binaries-v\(.*\)\.tar\.gz$/\1/')
3. Download the checksum, the signature and the public key for that version:
   for f in "kodachi-binaries-v$V.tar.gz.sha256" "kodachi-binaries-v$V.tar.gz.sig" "public_key_v$V.pem"; do curl -fLO "https://kodachi.cloud/downloads/installers/binaries/$f"; done

Copy the folder anywhere you like. In that folder (run step 2 again if you opened a new terminal), these three checks need no network:

1. Checksum, which must print OK:
   sha256sum -c "kodachi-binaries-v$V.tar.gz.sha256"
2. Signature, which must print Verified OK:
   openssl dgst -sha256 -verify "public_key_v$V.pem" -signature "kodachi-binaries-v$V.tar.gz.sig" "kodachi-binaries-v$V.tar.gz"
3. Unsafe paths, which must print 0:
   tar -tzf "kodachi-binaries-v$V.tar.gz" | grep -cE '^/|(^|/)\.\.(/|$)'

If any check fails, do not install it: see I saw signature verification warnings during install - should I abort?

Do not unpack the tarball and copy the files in by hand. A hand copy skips the root ownership of /opt/kodachi, /opt/kodachi/dashboard and /opt/kodachi/dashboard/hooks and the auth-trust folder. online-auth reads its public key and binary signatures only from that folder, so after a hand copy online-auth and the dashboard cannot log you in.

Kodachi 10 does this, and the stick then works the same on any machine you plug it into. Kodachi 8 did it with a casper-rw file on an Ubuntu base; Kodachi 10 is built on Debian live-boot, so the store is a persistence volume instead, and encrypted persistence, which Ubuntu's casper never allowed, is now a boot entry of its own. Four steps, done once.

1. Write the stick with a writable partition beside the ISO. The ISO itself is read-only, so a stick written with dd alone has nowhere to save to. Rufus (set a persistent partition size) and Ventoy (its persistence plugin) create the extra partition for you. If you wrote the stick another way, add an empty ext4 partition to it with GParted or fdisk and leave the ISO partitions alone. See My USB won't boot or only boots on some machines - did I write it correctly? for the write itself.

2. Turn that partition into a persistence volume. live-boot looks for an ext4 volume labelled persistence that holds a file named persistence.conf containing the single line / union. That line overlays your whole root, so dashboard settings, AutoShield, VPN profiles, the browser profile and the accepted terms all survive a reboot. Rufus and Ventoy write both for you. By hand, with the new partition at /dev/sdX3 (confirm it with lsblk first, the format erases it):

1. Format and label it:
   sudo mkfs.ext4 -L persistence /dev/sdX3
2. Mount it:
   sudo mount /dev/sdX3 /mnt
3. Write the one-line configuration:
   echo "/ union" | sudo tee /mnt/persistence.conf
4. Unmount it:
   sudo umount /mnt

From a running Kodachi session the same volume can be created as an image file instead. Open the stick's writable partition in the file manager so it is mounted, then run:

Add --encrypted for a LUKS image (you are asked for the passphrase). The command writes a file named persistence on the first writable removable partition it finds and reports the path as file_path; a path under /tmp means nothing writable was mounted, and a file there is RAM and vanishes at shutdown, so mount the partition and run it again.

3. Boot the persistent entry. At the boot menu press P for Kodachi Persistent, or N for Kodachi Encrypted Persistence, which asks for the LUKS passphrase and unlocks either an encrypted partition or the encrypted image file. The menu lives on the read-only ISO, so its ten-second default stays Kodachi Live, which saves nothing: pressing P is the one habit the stick needs. The difference between the two entries is in What is the difference between Persistent and Encrypted Persistence?. On the first persistent boot change the shipped password (What are the default username and password for the Terminal Server and Desktop editions?), because from now on it stays.

4. Configure once with AutoShield, then arm it. The dashboard opens at login. On the Quick Launch screen set the startup preference to Advanced, open the Advanced setup screen and its AutoShield tab, enable the steps your use case needs (Authenticate, the Kodachi VPN or your own profile, DNSCrypt, Tor, MAC randomization, the kill switch), pick a countdown and arm it. The armed check runs on the Advanced screen, which is why the preference matters: with Simple or Direct the countdown does not start on its own. The settings live in your account's own ~/.config/kodachi-dashboard/autoshield-settings.json on the persisted root, so from then on every boot into Persistent mode brings the dashboard up, counts down and applies your steps in order without a click, the same feel the Kodachi 8 auto-connect had. The step list and timers are described in Can I customize the AutoShield countdown timer and steps?.

Two things do not carry over: the boot menu choice, because the menu is on the read-only ISO, and anything you change in a plain Kodachi Live session.

Choose encryption while you install. In the graphical installer, pick Erase disk, tick Encrypt system and enter a passphrase you will not forget: it cannot be recovered, and without it the data is gone. Erase disk wipes the whole target disk, so back up first (what installing erases). The installer offers no swap, a small swap partition or a swap file; with an encrypted disk, a swap file lives inside the encrypted volume.

Your own layout, for example a separate /home: choose Manual partitioning in the graphical installer, or the Install Kodachi (Text Mode - Manual Partitioning) entry in the ISO boot menu's Advanced options & fallback modes... submenu, and set encryption per partition there. The EFI system partition always stays unencrypted, because the firmware has to read it.

If you want the boot-time LUKS nuke password as well, install with the Debian text installer instead: from the ISO boot menu open Advanced options & fallback modes... and pick Install Kodachi (Text + Full Disk Encryption, Boot-Nuke Compatible) (which installer the nuke needs).

Encrypted Persistence in the boot menu is something else: it encrypts the persistence volume of a live USB stick, not an installed system (Persistent and Encrypted Persistence).

An existing installation cannot be encrypted in place safely; doing it by hand is easy to leave unbootable. Reinstall instead, keeping your files and your list of apps:

1. Save the list of apps you installed into Documents, so the backup carries it:
   apt-mark showmanual > ~/Documents/my-packages.txt
2. Back up with Kodachi Backup to an external drive (backing up before an install). Note anything you installed outside apt, such as AppImages or files in /opt.
3. Boot the Kodachi ISO and reinstall with Erase disk and Encrypt system as above.
4. Restore the backup in the new system. Files come back into a staging folder, so nothing is overwritten. Then refresh the package lists:
   sudo apt update
   And reinstall your apps from the saved list:
   xargs -a ~/Documents/my-packages.txt -n1 sudo apt install -y

Timeshift is good for rolling the same system back, but it is not made for moving to a fresh encrypted install, so use Kodachi Backup for this.

Your installed system is fine; the firmware started the fallback copy of GRUB, which found no configuration. This happened mostly with external and second SSDs installed from earlier 10.x ISOs: the first boot used the installer's boot entry, and once the firmware dropped that entry it fell back to a copy without a configuration file. Boot it by hand at the grub> prompt, typing these two lines one at a time:

Kodachi then starts normally. Make the fix permanent by updating; the core package writes the missing fallback boot configuration during the update:

You can also run the repair tool directly:

Reboot to check. Current ISOs write this configuration during installation. The tool never overwrites a fallback configuration that belongs to another operating system on the same disk; if it prints a WARNING instead, it names the one-line repair for your case, and on a shared disk you can simply pick Kodachi in your firmware's boot menu. If the search line reports file not found, type ls at the prompt and post a photo of its output in the Discord support channel (where to get help). For other start-up failures, such as a black screen or a BusyBox shell, follow If the system will not boot.

Secure Boot is working and the firmware refused the boot file it was given, so check two things in turn: the firmware keys, then the boot chain. Switch Secure Boot off again so Kodachi boots while you fix it.

1. Firmware keys. Secure Boot can only be switched on while the firmware's own keys are loaded. If the firmware shows PK unloaded or Setup Mode, or offers no way to turn Secure Boot on, install the default keys again. On ASUS boards: press F7 for Advanced Mode, open Boot, Secure Boot, Key Management, choose Install Default Secure Boot keys (Restore Factory Keys on some boards), keep CSM disabled and save with F10. ASUS boards have no separate switch: OS Type Windows UEFI Mode turns Secure Boot on and Other OS turns it off, and Secure Boot State: User only means the keys are loaded.

2. Is the signed shim on the disk?

If it finds nothing, the system was installed before Kodachi set the shim up. On an unencrypted install, run the repair (it needs the internet; if the command is not found, update Kodachi first):

Then reboot once with Secure Boot still off and check that Kodachi starts. After that, switch Secure Boot on and boot Kodachi; if the violation stays, go to step 3.

3. Does the boot entry start the shim? If the shim is there and the violation stays, look at the file the firmware starts:

If the Kodachi entry ends in GRUBX64.EFI instead of shimx64.efi, GRUB is started directly. On an unencrypted install, run the same repair as in step 2: it sees that the entry does not load the shim, rewrites the boot files through the shim and points the entry at it.

If it answers that the shim is already present and the ESP needs nothing while the entry still ends in GRUBX64.EFI, your copy of the repair is older than this fix: update Kodachi and run it again. Then reboot once with Secure Boot still off and check that Kodachi starts, run the efibootmgr check again (the entry now ends in shimx64.efi), then switch Secure Boot on. Never install shim-signed or grub-efi-amd64-signed with apt by hand; if the repair refuses, it says why, and you can ask on Discord.

Encrypted install: do none of the boot-chain steps and keep Secure Boot off. A boot-chain change on an encrypted install can leave GRUB unable to open /boot, and the next boot stops at a grub> prompt. The full walkthrough is the Secure Boot guide.

Tirdad and the other add-on kernel modules still need a key you enrol yourself before they load with Secure Boot on: see using Tirdad with Secure Boot.

Any host that still receives security updates and has enough memory for two systems at once: a current Linux (Debian, Linux Mint Xfce or Xubuntu run well on older hardware) or Windows 11. A virtual machine does not make an unpatched host safe, because everything the guest sends and receives passes through the host first.

Windows 7 can still run older virtualization software, but its support ended on 14 January 2020, so it should not be the machine you put on the internet. Standard support for Windows 10 ended on 14 October 2025.

Memory matters more than the host's name. The Desktop edition needs at least 8 GB of RAM for the guest alone and the Terminal edition 4 GB, and the host needs its own memory on top of that. With 4 GB in total, boot Kodachi from a USB stick instead (running from USB). The VM settings that matter are in testing Kodachi in a VM.

The GRUB menu has 8 main entries organized by security tier (Tier 1 lightest to Tier 5 strongest): Kodachi Live (Tier 1, hotkey L), Kodachi Persistent (Tier 2, P), Kodachi Encrypted Persistence (Tier 3, N), Kodachi CPU Hardened (Tier 3, U), Kodachi Maximum Privacy (Tier 4, M), Kodachi Kernel Lockdown (confidentiality) (Tier 4, S), Kodachi Forensics Mode (Tier 5, F), and Kodachi Full Hardening (Tier 5, H). An 'Advanced options & fallback modes' submenu (hotkey A) adds DMA Protection, Hardened Malloc, Full RAM mode, Performance Balanced, plus hardware fallbacks (nomodeset, noapic, legacy NIC names, GPU/VESA modes), text-mode fallback, installer entries, and utilities like Memtest86+ and media integrity check. The first entry, Kodachi Live, is the default and the fastest to boot.

For most people the default Kodachi Live (Tier 1) is the right choice: it has a low RAM footprint, the fastest boot, and is ideal for testing, demos, and hardware compatibility checks. If you want to save changes between sessions on trusted hardware, use Kodachi Persistent (Tier 2); if you want that data encrypted, use Encrypted Persistence (Tier 3, LUKS-protected). Stronger profiles lower in the menu enable extra security controls and can boot slower or cause some services to fail, so only move up a tier when you actually need the extra hardening.

Kodachi Persistent (Tier 2, hotkey P) saves your changes to a persistence volume without encryption, which keeps it fast and low-overhead but means the data is readable if the media is lost or seized. Encrypted Persistence (Tier 3, hotkey N) stores the persistence volume inside a LUKS-encrypted container, so you are prompted for a password at boot and your saved data stays protected at rest. Encrypted Persistence trades a slightly slower, moderate boot for password-protected long-term storage; choose it when persistence data must remain confidential.

Use Kodachi Full Hardening (Tier 5, hotkey H) for high-threat or adversarial environments: it enables module signature enforcement, integrity lockdown, IOMMU/DMA protection, memory-hardening flags and the generic mitigations=auto pti=on, at the cost of the slowest boot and a real chance that some services or hardware will not work. Use Kodachi CPU Hardened (Tier 3, hotkey U) specifically for CPUs vulnerable to Spectre/Meltdown-class speculative-execution attacks, especially on legacy or cloud hardware. The tiers became a strict superset chain on 2026-09-04: Tier 4 and Tier 5 (Maximum Privacy, Kernel Lockdown, Forensics, Full Hardening) now all include the whole CPU Hardened set, so moving up a tier no longer loses a mitigation. Two consequences worth knowing before you choose: mds=full,nosmt disables SMT, so CPU Hardened and every entry above it run on half your CPU threads (Encrypted Persistence is also Tier 3 but does not carry that set), and Forensics now carries lockdown=integrity, so it refuses the same out-of-tree DKMS drivers the other hardened tiers already refused. For everyday privacy with good speed, stay on Live, Persistent, or Encrypted Persistence - the docs note a score of 50-65 with VPN, DNSCrypt and firewall active is already more secure than 99% of operating systems.

Kodachi Forensics Mode (Tier 5, hotkey F) boots into RAM and avoids intentionally mounting or writing target disks by default, making it useful for volatile-memory and incident analysis. This is a default behavior, not a universal no-trace guarantee: operator actions, mounted filesystems, and forensic tools can write data when configured to do so. It has a high RAM footprint and does not wipe memory on shutdown by default; enable that explicitly from the Dashboard or with:

It also disables IPv6 at the kernel level, and so does every other entry in the live menu, so there is no lower tier to reboot into for runtime IPv6: edit the entry at the boot menu with e and remove ipv6.disable=1 if you need it.

Kodachi Maximum Privacy (Tier 4, hotkey M) is a RAM-only session focused on anti-tracking: debug hooks are disabled, the session runs fully in memory, and freed memory is zeroed as it is released (init_on_free=1), making it good for sensitive privacy and anonymity tasks. No boot entry wipes RAM at shutdown on its own: that is opt-in, from the Dashboard or with:

Because it runs entirely in RAM it has a high memory footprint, though it still boots fast. It disables IPv6 at the kernel level (ipv6.disable=1), so the Dashboard IPv6 toggle cannot bring IPv6 back, and no other menu entry can either: every one of the 23 live boot entries carries that flag, so there is no lower tier to reboot into for runtime IPv6. To get IPv6 on a live session you have to edit the entry at the boot menu, press e, delete ipv6.disable=1 from the linux line and press Ctrl-X.

Kodachi Kernel Lockdown (confidentiality) (Tier 4, hotkey S) enforces signed kernel modules and applies lockdown policies (lockdown=confidentiality, module.sig_enforce=1) for systems running with UEFI Secure Boot enabled and trusted boot chains. It has a moderate RAM footprint and moderate boot speed. Be aware that on this mode the kernel refuses every out-of-tree module whose signing key it does not trust, which covers all 37 DKMS modules Kodachi ships - AmneziaWG, Tirdad, and the Broadcom and Realtek Wi-Fi drivers - so they will correctly show as blocked - that is expected behavior, not a bug.

Open 'Advanced options & fallback modes...' (hotkey A) at the boot screen for specialized and recovery entries: DMA Protection (adds IOMMU/DMA protection to the base profile, hotkey D), Hardened Malloc (adds the memory-hardening set), Full RAM mode (adds toram, needs 8 GB RAM, hotkey R), and Performance Balanced (the same kernel command line as Kodachi Live). These four are single-axis modifiers on the base profile rather than rungs of the main menu's tier chain, so they deliberately carry no star rating. It also contains hardware-compatibility fallbacks (text/no-GUI mode, old NIC names, noapic, acpi=off, nomodeset, GPU/VESA fallbacks, maximum-compatibility), the text and unattended installer entries (including encrypted Boot-Nuke-compatible variants), and utilities like Memtest86+, 'Check disc for defects', chain-loading the first disk, and UEFI Firmware Settings.

Use the right boot tier and the right hardware. Kodachi Live (Tier 1) has the lowest RAM footprint and the fastest boot; RAM-resident modes like Maximum Privacy and Forensics and the heavier hardening tiers consume much more memory and stronger profiles can boot slower. The release record lists minimums of 8 GB RAM and 20 GB storage for the Desktop edition and 4 GB RAM and 10 GB for the Terminal edition; an SSD/NVMe and more RAM make the biggest difference, especially for RAM-only modes. In the Dashboard, turn on Performance mode (Settings) to disable all visual/glass/glow effects and animations at once on low-power hardware, and use the quick animations toggle when the UI feels heavy.

The documentation does not state any specific boot-time figure, so a fixed claim like 'under 30 seconds' is not something Kodachi publishes. Boot time depends on your hardware and the boot tier you pick: the docs describe Kodachi Live as the fastest profile, Persistent also fast, Encrypted Persistence and Kernel Lockdown (confidentiality) moderate, and CPU Hardened and Full Hardening the slowest because they enable extra security controls. RAM-resident modes (Maximum Privacy, Forensics, Full RAM) are fast to start but need more memory. For the quickest boot, use Kodachi Live on an SSD with adequate RAM and avoid stacking heavy hardening features.

Yes, at two levels. On the Desktop edition, AutoShield is the easy guided automation - the Kodachi Dashboard's first-boot wizard that runs a configurable set of hardening steps with a countdown timer. For far more power and customization, the workflow-manager binary runs batch command sequences with conditional logic, pattern/JSON matching, retry logic, pause checkpoints, dry-run testing and JSONL telemetry. It ships with 122 ready-to-use built-in profiles in dashboard/hooks/config/profiles/ and supports unlimited custom workflows. On the Desktop, Lite Classic lets you drag commands into a queue, reorder them, and run them sequentially or in parallel.

Yes. The ai-scheduler binary is a cron-based task scheduler for automated Kodachi operations. It uses standard cron expressions, enforces a strict command whitelist for security, and stores tasks persistently so they survive service restarts. It is ideal for recurring security checks, Tor circuit rotations, DNS leak tests, and AI learning cycles. Run it with ai-scheduler (the daemon needs sudo for scheduled privileged commands).

Two. The Kodachi Desktop Edition is built on Debian 13 (Trixie) with an XFCE GUI, the Kodachi dashboard, Conky system monitor, LibreWolf browser and 10 dynamic application layers - the full graphical experience. The Kodachi Terminal Server is a headless, command-line-only build (a lightweight ~3GB ISO with no GUI bloat) optimized for testing, dedicated SOCKS proxy deployment and server operations. Both editions ship every binary pre-installed and configured.

Yes, with options to keep it light. The Terminal Server edition has no GUI at all and is the lightest choice for old or constrained hardware and headless servers. On Desktop, Circle uses roughly ~230MB RAM and Lite Classic roughly ~300MB (Vitals and SOC ~240MB, ColonyOps ~260MB), and you can cut more overhead by enabling the dashboard Performance mode (disables glass blur, glow and animations) and turning off the Conky overlay to free 3-8% CPU.

LibreWolf blocks .onion domains by default per RFC 7686. The simplest fix is to use Tor Browser, which handles .onion natively with its own built-in circuits and no system torrification needed. To use .onion in LibreWolf you must first torrify the system, then in about:config allow .onion and disable the built-in proxy, and add a top-priority SOCKS5 entry in the pre-installed FoxyProxy extension pointing at 127.0.0.1 with Proxy DNS enabled on the correct Tor instance SocksPort.

Tor Browser uses its own built-in independent Tor circuits, separate from system torrification, so it naturally shows a different exit than the system. Additionally, under load-balanced torrification the widget, browser, and integrity panel can each show a different genuine Tor exit at the same time because Kodachi runs multiple parallel Tor instances. This is expected, not a misconfiguration.

Those entries set the kernel flag ipv6.disable=1, so the IPv6 stack is never initialized and /proc/sys/net/ipv6/ does not exist. The dashboard and health-control ipv6-enable work through sysctl, which cannot bring back a stack that was never created, and no reboot into a different menu entry changes that: every one of the 23 live boot entries carries ipv6.disable=1, main menu and Advanced submenu alike, so there is no live entry where the runtime IPv6 toggle can work. (Earlier versions of this answer named Live, Persistent, Encrypted Persistence and CPU Hardened as lower-tier entries that keep IPv6 available. They do not, and that advice was wrong.)

The stack is deliberately off for leak protection, and for most users that is the desired state. If you genuinely need IPv6 on a live session, edit the entry at the boot menu: highlight it, press e, delete ipv6.disable=1 from the linux line, and press Ctrl-X to boot that one time. On an installed system, remove the flag from the Kodachi entries in /etc/grub.d/07_kodachi_security_modes (it is in the shared BASE_ARGS, not per-entry), run:

Then reboot.

Stronger hardening profiles enable extra controls - module signing, kernel lockdown, IOMMU, anti-tracking, disabled debugfs - that can intentionally break some commands, services, or hardware detection, and they boot slower and use more RAM. This is expected fail-closed behavior. Reboot and pick a less restrictive profile such as 'Kodachi Live' (Tier 1), the lightest and fastest default.

Open Essentials > Actions > Network Recovery > Fix Internet Wizard and read the pre-fix badges. If the host is torrified, trust the HTTP connectivity check more than the ping check, because ICMP ping is unreliable through Tor. Run the normal queue first (full auto recovery, flush DNS, fallback DNS, fix DNS); if it still fails, expand Advanced Steps (recover routing, toggle DNS mode, restart DNSCrypt, or detorrify when Tor firewall rules are the blocker).

Use the Enable DNSCrypt row's chevron menu in AutoShield (or Essentials > DNS). Check DNS Status, then run Safe DNS Repair, which restores encrypted DNS without breaking active tunnels. Only if that fails use Forced DNS Repair, which resets all DNS config. Verify with a DNS Leak Test, and if Tor is active switch to Tor DNS to route DNS through Tor circuits.

systemd-resolved can take over the resolver and override DNSCrypt. AutoShield continuously verifies DNSCrypt is the active resolver and includes auto-recovery that detects the hijack and restores DNSCrypt, retrying configuration up to 3 times with short delays before falling back to direct DNS. If it stays broken, force reconfiguration with:

On first login AutoShield creates a marker file 'results/dns-configured' in the hooks directory specifically so DNSCrypt setup does not re-run on every subsequent login. Because the marker exists, normal logins skip reconfiguration. Force it to run again with this, which ignores the marker:

DNSSEC adds cryptographic signatures to DNS records so your resolver can verify that answers haven't been tampered with in transit. On Kodachi the encryption layer is dnscrypt-proxy, not systemd-resolved, so the canonical command is:

This sets require_dnssec = true in /etc/dnscrypt-proxy/dnscrypt-proxy.toml and restarts dnscrypt-proxy automatically. With validation on, only signed upstream responses are accepted; unsigned responses are silently rejected, which can break resolution for domains that haven't deployed DNSSEC yet. Disable it with:

Enabling DNSSEC earns +0.1 dns_privacy points in the health-control security score.

DoH encrypts DNS queries inside HTTPS to port 443, so they look like ordinary web traffic to a casual observer and are harder to block or intercept than plain DNS (traffic analysis can still tell DoH servers apart). It is functionally equivalent to DNS-over-TLS (DoT) but uses the standard HTTPS port. On Kodachi run:

This sets doh_servers = true in /etc/dnscrypt-proxy/dnscrypt-proxy.toml and restarts dnscrypt-proxy to allow DoH-capable resolvers. Disable with:

Do not bother editing /etc/systemd/resolved.conf on Kodachi, as systemd-resolved is typically inactive and won't affect live DNS traffic. Enabling DoH earns +0.2 dns_privacy points in the health-control security score.

AutoShield detected no internet connectivity and switched to offline mode. Online data (crypto prices, news, online authentication) needs to reach the Kodachi VPS; offline it shows placeholders and uses local DNS instead. All local features remain fully functional - restore connectivity and the data refreshes on the next periodic refresh cycle.

The core binaries install to /opt/kodachi/dashboard/hooks (or your --desktop/--path location), which is not on PATH unless the installer added it to ~/.bashrc (skipped with --skip-path or in a fresh shell). Verify with:

Then check $PATH, and either run by full path (/opt/kodachi/dashboard/hooks/ip-fetch) or add the directory to PATH for the current shell with:

For permanent system-wide access run:

And check deployment integrity with:

No post-boot installation is required. firmware-b43-installer and firmware-b43legacy-installer are intentionally excluded because they fetch firmware over the network at install time, which would break the offline ISO build; instead the b43 and b43legacy firmware is pre-extracted on the build host (b43-fwcutter) and shipped in the ISO under /lib/firmware/b43/ and /lib/firmware/b43legacy/, and broadcom-sta-dkms is included for the proprietary wl driver. Kodachi also bundles firmware for Intel, Atheros/Qualcomm, Realtek, MediaTek and others. If WiFi still fails on a strict hardening profile, reboot into Live or Persistent for broader compatibility.

WiFi is commonly soft/hard-blocked by rfkill or put to sleep by power management. Check with:

Then unblock it with:

Bring the interface up, and check for missing firmware with:

For frequent drops disable radio power saving and verify the regulatory domain, since a wrong country code restricts channels:

The default Kodachi Live mode does not persist session changes to the live medium. That does not mean no storage can ever be written: filesystems you or a tool mounts can still receive writes. To keep Kodachi configuration, boot Kodachi Persistent or Kodachi Encrypted Persistence, which require a persistent partition. USB writers may create that partition when their persistence option is enabled, or you can use the dashboard and health-control persistence tooling. The step-by-step setup of a stick that keeps its settings is in How do I make a Kodachi USB stick that keeps my settings and comes up configured on every boot?.

Kodachi does not ship a built-in Remaster or ISO Creator tool, and there is no official one-click way to repack your customized installation back into a Live ISO. That is by design: Kodachi is assembled upstream from clean Debian using Debian live-build, driven from source recipes on the maintainer side, not captured from an already-installed running system.

What you want, capturing a configured system into a fresh non-persistent Live ISO, is a standard Linux remastering task, and mature community tools handle it. For a Debian-based system like Kodachi the best fit is Penguin's Eggs (penguins-eggs.net). Run it from your customized Kodachi system:

1. One-time interactive build config:
   sudo eggs dad
2. Snapshot the running system into a bootable Live ISO:
   sudo eggs produce

The resulting ISO includes your extra apps, wallpaper, theme and shortcuts, and boots in normal non-persistent Live mode by default, so browser data, cookies, sessions, profiles and logins are discarded on every reboot. Other options are Linux Respin or Systemback (similar approach, less actively maintained); avoid Cubic, which only edits an existing ISO and does not capture your running setup.

Two cautions. First, clean your secrets before building: anything present at capture time is baked into the image, so clear browser profiles, accounts, shell history, SSH keys and saved credentials first; non-persistence only protects data created after boot, not what was already there. Second, the result is your own derivative image, not an official Kodachi release, so it does not carry my signed integrity hashes or the signed update/verification chain. If you want these apps in an official signed build, send me the request to evaluate for upstream inclusion instead of remastering on your side.

Forensics Mode boots fully in RAM and avoids intentionally mounting or writing target disks by default. That default does not prevent an operator or forensic tool from writing mounted storage. It also does not wipe memory on shutdown by default. Maximum Privacy is geared toward automatic memory wiping; under Forensics Mode, enable RAM wiping explicitly through health-control or the dashboard.

Those profiles copy the live system into RAM with toram, which reduces reads from and writes to the live medium but uses substantially more memory. It does not make every disk read-only: mounted or tool-controlled disks remain writable. On low-RAM hardware these modes can exhaust memory; use the normal Kodachi Live entry for lower RAM use and faster startup.

It can hurt plausibility. The default Randomize Timezone step deliberately mismatches IP geolocation and system clock, which is fine for pure anonymity but can flag sites that check timezone consistency. If you use a VPN with a known exit country, use the Sync Timezone button instead - it queries your public IP geolocation and sets a matching timezone, making your identity more plausible. To check it at a glance, the Time zone chip in the left sidebar of kodachi.cloud says whether your browser's time zone fits your exit country.

It is intentional, not a fault. LibreWolf uses DNS-over-HTTPS in TRR mode 3 (fail-closed), forcing all DNS through encrypted channels with no plaintext fallback so DNS cannot leak; it excludes localhost and kodachi.local so VPN/Tor routing still works. If a site fails to resolve, the encrypted-DNS path is failing closed by design rather than silently leaking - run Safe DNS Repair instead of disabling the protection.

The Rust conky-status telemetry gateway (legacy conky-details name) drives the Conky desktop telemetry display, which is a Desktop XFCE feature (the Terminal edition has no GUI/desktop to render it). The binary itself ships in the unified 29-binary pack at /opt/kodachi/dashboard/hooks/ on current Terminal ISOs, but its desktop telemetry display is only active on Desktop XFCE builds.

The KAICS binaries (ai-cmd, ai-gateway, ai-trainer, ai-learner, ai-admin, ai-discovery, ai-scheduler, ai-monitor) ship pre-installed in the unified binary pack, but the natural-language workflows depend on AI models and services that are enabled on demand rather than active out of the box on Terminal. The commands are documented for completeness; enable the KAICS add-on (models/services) for them to run.

Security4All is only the password for the default kodachi live account, set during build. Root login is disabled and does not use this password by design. Use the kodachi account (passwordless sudo via the sudo group) and run privileged commands with sudo rather than attempting a direct root login.

The session helper enforces a minimum hold duration of 500ms for emergency shortcuts; any configured value below that is rejected for safety so a brief accidental key combination cannot fire a destructive action. Set the hold duration to 500ms or higher (the helper's built-in times are 1.5 to 2.5 s by action; 2 s is the recommended choice in Settings).

No. Auto-login is intentionally DISABLED via a getty override during the build; the live session expects you to log in as the kodachi user (password Security4All) rather than dropping straight to a desktop. This is a deliberate hardening choice, not a misconfiguration.

This is a normal pattern, not a regression. Kodachi 8 shipped with far fewer features than Kodachi 9 and 10, so a smaller system naturally feels lighter. Kodachi 9 was written from scratch rather than patched on top of 8, which means a brand-new codebase could not be as battle-hardened on its first release as a version that had years of fixes. The exact same thing was said when v7 replaced v6, and again when v8 replaced v7: the older version always feels more stable at first because it is more mature, and then the new one catches up and overtakes it as it settles. Kodachi 10 continues the Kodachi 9 codebase on the same Debian 13 base (the 10 boundary is a version re-anchor and a licence change, not a rewrite) and carries a much larger surface than 8 (the full Kodachi dashboard, the Rust binaries, the AI stack, workflows, live scoring). Staying on 8 means staying on a smaller, no-longer-developed feature set that no longer receives fixes.

Kodachi ships 37 out-of-tree DKMS kernel modules, and every one of them is refused by any boot entry that enforces module signatures. They are not unsigned: they carry a signature made with a certificate that is generated while the image is built and that no computer has been told to trust, so the kernel reports signature and/or required key missing and declines to load them. What you lose is the same list every time: AmneziaWG (the obfuscated VPN transport, module amneziawg), Tirdad (TCP initial-sequence-number randomisation, a privacy hardening module), Broadcom STA Wi-Fi (wl), and 34 Realtek Wi-Fi drivers (8814au plus 33 rtw_* modules for USB and PCIe adapters). Everything else on the system is a Debian in-tree module signed by Debian, including WireGuard, OpenVPN's kernel pieces, Intel and Atheros wireless, so ordinary networking is unaffected.

Four main-menu entries enforce this: Kernel Lockdown (confidentiality) (module.sig_enforce=1 and lockdown=confidentiality), Full Hardening (module.sig_enforce=1 and lockdown=integrity), Maximum Privacy and Forensics Mode (both lockdown=integrity; Forensics joined them on 2026-09-04 when the tiers became a strict superset chain). The same thing happens on any entry when UEFI Secure Boot is turned on in firmware, because the kernel then enables lockdown by itself. These entries do not enforce it and run the full driver set: Kodachi Live, Persistent, Encrypted Persistence, CPU Hardened, and every entry in the Advanced submenu (DMA Protection, Hardened Malloc, Full RAM, Performance Balanced, the graphics and NIC fallbacks). On those, the kernel loads the module and prints a one-line taint notice, which is expected and harmless. To see which state you are in, run these three; in the first, the value in brackets is active:

If a driver or AmneziaWG is missing, reboot and pick Kodachi Live or CPU Hardened.

Use the XFCE Desktop edition, or install Kodachi's tools on a Debian or Ubuntu system that runs GNOME, KDE or any other desktop: the Kodachi binaries and the dashboard install there too (the binaries on Debian or Ubuntu, installing single packages). Builds like that are welcome from the community; they are not official editions and are not tested to the same level.

XFCE is the only official desktop, on the Desktop edition and its smaller variants, all built on Debian 13. Kodachi is developed by one person, and every desktop it ships has to be integrated, kept secure and tested to the same standard, so the work goes into one desktop done properly. XFCE is also light and quick, which suits older hardware. For a server without any desktop, use the Terminal edition (choosing an edition).

Set it in XFCE first: open Settings → Display, pick the resolution and refresh rate, apply, and keep the change; XFCE remembers it for that monitor and applies it again at login.

If the resolution is not in the list, the monitor did not report it, and you can add it with xrandr. List your outputs and their names:

Generate a mode for your size and refresh rate:

Create the mode from the numbers cvt printed after Modeline, add it to your output (DP-1 here; use the name xrandr showed) and switch to it:

To keep it after a reboot, run those three lines at login from Settings → Session and Startup → Application Autostart: add an entry whose command is sh -c 'sleep 3; xrandr --newmode ...; xrandr --addmode ...; xrandr --output ...' with your own lines. The short pause lets XFCE finish applying its own display settings first.

If the Conky panels end up out of place after a resolution change, turn Conky off and on again (hiding and restoring Conky).

The Kodachi Dashboard is the central control application that orchestrates 606 generated commands across 26 registered CLI services provided by 25 command-bearing binaries, with async execution so long commands do not freeze the GUI. On the Desktop edition it auto-launches at login and offers five switchable dashboards (the free Circle command wheel, the free Lite Classic command center, the premium Vitals monitor, the premium SOC security monitor and the premium ColonyOps operations workspace), plus AutoShield, its guided first-boot setup wizard. It manages authentication, VPN/routing, Tor, DNS, identity randomization, hardening, monitoring and recovery, and presents an adaptive 0-100 security score across seven weighted categories.

You can run day-to-day privacy operations entirely from the Dashboard - all five dashboards share the same backend of 606 generated commands across 26 registered CLI services provided by 25 command-bearing binaries, and the Lite Classic Actions tab bundles authentication, DNS, Tor, identity randomization, power controls, connection, and the full network-recovery block. If you do not know which binary provides a feature, the Library tab indexes every command with descriptions, danger levels, and required authentication status. The terminal is available for scripting and advanced one-off commands (the same binaries like health-control and online-auth are CLI tools), but it is optional for normal use.

The Dashboard has five switchable dashboards: Circle (sliced command wheel with profile and level controls, free, restores to 1400x1000, ~230MB RAM, Beginner to Advanced, and the default), Lite Classic (the main categorized command center, free, restores to 1400x980, ~300MB RAM, Beginner to Advanced), Vitals (live system monitor, premium, 1400x1020, ~240MB RAM), SOC (live security monitor, premium, 1400x1020, ~240MB RAM) and ColonyOps (workflow and operator workspace, premium, 1280x860, ~260MB RAM, Intermediate to Expert). Every dashboard opens maximized on first run, so those figures are the size it restores down to. You pick one on the startup launcher, and you can switch at any time from the Dashboards button on the left rail, which every dashboard shares; dashboards you have not activated are shown locked rather than hidden, and your last choice is remembered. AutoShield is offered as an extra option in the first-boot welcome screen but it is a guided setup wizard route rather than a persistent interface mode (it is not one of the five dashboards in the mode store). You can re-open AutoShield any time from the shield icon in the dashboard header.

On the Desktop edition it is the Kodachi Dashboard that auto-launches at login (via the ~/.config/autostart/kodachi-dashboard.desktop entry, which runs kodachi-dashboard-launcher), not AutoShield by itself. AutoShield is the Dashboard's first-boot wizard mode/route: on first run the Dashboard shows a welcome screen and offers AutoShield as a guided setup option alongside the five dashboards. It is a countdown-driven hardening console covering identity randomization, secure routing, DNS setup and live verification, and you can re-open it any time from the shield icon in the dashboard header. It carries 29 configurable controls across eight categories (Identity, Connectivity, DNS, Tor, Hardening, Hardware, Maintenance, and Boot Profiles) with a countdown timer and a before/after identity comparison. Only 3 are enabled by default (Authenticate, Randomize Hostname, Randomize Timezone); everything else, including MAC randomization, VPN connect, DNS mode and Torrify, is off until you turn it on, and when the countdown reaches zero it auto-executes the enabled ones. On the Terminal edition there is no GUI wizard at all: 'AutoShield' there is the login-shell information screen and interactive menu at /etc/profile.d/kodachi-autoshield.sh, run with the welcome or shield command.

Running at every boot. Once you arm it, AutoShield runs your enabled steps when the dashboard starts, whichever startup screen you use (Simple, Advanced or Direct), once per boot (commands at boot). The default countdown is 10 minutes, so pick a shorter one when you arm it. If you press Launch before it has run, the launcher asks whether to Run AutoShield first or Skip & launch now; skipping leaves it armed for the next boot. Older 10.x builds started an armed AutoShield only from the Advanced startup screen, so if yours waits for you on Simple or Direct, update (updating without a new ISO).

Yes. AutoShield offers multiple countdown modes (60 seconds, 2 minutes, 5 minutes, 10 minutes, plus longer presets and a Manual no-auto-execute option). It has 29 configurable controls across eight categories; only 3 are enabled by default (Authenticate, Randomize Hostname, Randomize Timezone) and the remaining 26, including Randomize MAC, VPN Connect, DNS Mode, Torrify and Harden PC, are disabled until you enable them. Timer duration, step toggles, the auto-refresh interval and other preferences persist across reboots via the autoshield-settings.json file. Use a short timer for rapid hardening on boot, or Manual when you want to inspect every step first.

Yes, and closing the window already hides it to the tray by default. In Settings, Dashboard, the Startup tab has Auto-start on boot to launch the dashboard automatically, Start minimized to tray to launch it hidden, and Show welcome screen. The Desktop tab has the System Tray card: Show tray icon, and Close to tray instead of exit, which is on by default, so the X button hides the dashboard while it keeps running. Click the tray icon's Show Dashboard to bring it back, or Quit Kodachi to close it fully; turn Close to tray instead of exit off if you want X to quit. Always on top, which pins the dashboard above other windows, is on the General tab.

Both are at-a-glance protection-status indicators that read the same live state as the dashboard. When you minimize or close the dashboard to the system tray, the tray icon shows three colored dots, read left to right: the left dot is Login (your online-authentication session is active), the middle dot is VPN (a VPN such as WireGuard is connected), and the right dot is Tor (the system is torrified / routing through Tor). Each dot is green when that layer is on/connected/active and red when it is off/disconnected/inactive - so all three green means you are logged in with both VPN and Tor engaged, while only the left green means you are authenticated but neither VPN nor Tor is active. The icon updates automatically as state changes, letting you monitor your posture without reopening the window. Left-click the tray icon to show or hide the dashboard, and right-click for the full quick-action menu. Hover tooltips do not render on Linux tray backends, which is exactly why the three dots exist as the indicator.

On the desktop, the Conky overlay carries a matching indicator: the small security-status square at the top-left of the Conky gauges panel. It is a grid of little blocks split into four quadrants - top-left is Authentication (logged in to Kodachi), top-right is VPN, bottom-left is Torrified (Tor routing), and bottom-right is DNS (DNSCrypt or Tor DNS). Each quadrant lights up cyan when that protection is active and stays dim/faded when it is off, so all four glowing cyan means authentication, VPN, Tor and encrypted DNS are all engaged, and any dim quadrant shows which layer is not yet active. It gives you a desktop-level status check without opening the dashboard. You can hide or screenshot-mask the Conky overlay from Settings > Dashboard > Conky Control.

Yes - the Kodachi Dashboard is locked behind a multi-layer authentication system: a strong password plus optional TOTP two-factor (compatible with any authenticator app), 8 single-use recovery codes, configurable auto-lock timeouts (1 minute up to 4 hours or never), and a full tamper-resistant audit log of every auth event. Separately, many privacy actions also require logging in to Kodachi cloud services (online-auth) to unlock premium features like VPN routing and the full identity-randomization step set; non-authenticated users in AutoShield can still run Authenticate (Re-login), Standard recovery, and DNSCrypt (encrypted). Repeated failed logins escalate through four configurable automated threat-response levels.

The Routing Guide is the dashboard's decision helper for choosing the right privacy path before you start switching protocols manually. It translates Kodachi's routing stack into plain-language tradeoffs - speed, account safety, censorship resistance, DNS privacy, and layered anonymity - so you can decide whether you need WireGuard, OpenVPN, anti-censorship transports, Tor, DNSCrypt, or a workflow-backed layered setup. For new users it makes the dashboard understandable without learning every binary first; for experienced operators it reduces mistakes like picking the wrong route for logged-in accounts or combining VPN and Tor in the wrong order.

Circle mode opens maximized and restores to 1400x1000. Its default Protection profile carries 7 clickable stations - Authenticate, MAC Randomize, Hostname Spoof, Random Timezone, DNS Privacy, VPN / Proxy / Tunnel, and Torrify System - surrounding a central hub that shows your real-time IP, country flag, and a color-coded security score from 0 to 100. A profile picker swaps the wheel between Protection, Identity, Hardening and System, with Beginner / Intermediate / Advanced levels controlling how much of each profile is exposed. It celebrates milestones with victory animations at 25%, 50%, 75%, and 100% completion, dual auto-refresh (30s for IP/status, 60s for deep metrics), and 4 emergency controls (Routing Recover, Internet Recover, Restart Tor, Secure Shutdown). It is the beginner-friendly mode at roughly 230MB RAM.

Yes. The top status bar has a Compact Mode icon that shrinks the window until only the top bar is visible, to create a minimal workspace - useful on small screens or when you want the dashboard visible but out of the way. Click it again to restore the full window. It is a per-view toggle and is separate from the Dashboards button on the left rail, which switches between the five dashboards rather than just resizing the window.

They are different things. Compact Mode is a quick top-bar toggle that shrinks the window until only the top bar is visible, in whatever dashboard you are in. Lite Classic is a full dashboard choice, picked on the startup launcher or from the Dashboards button on the left rail - it opens maximized, restores down to 1400x980, and carries a collapsible sidebar of 16 pages in three groups: Overview (Actions, Health, AI Chat), Essentials (10 pages) and Command & Monitor (Command Library, Command Builder, Monitor). You can use Compact Mode in any dashboard.

There are five dashboards plus AutoShield. Circle is the free sliced command wheel with 7 stations per profile (restores to 1400x1000, ~230MB RAM, Beginner to Advanced, and the default). Lite Classic is the free main command center with a 16-page sidebar in three groups plus a drag-and-drop command queue (restores to 1400x980, ~300MB RAM, Beginner to Advanced). Vitals is the premium read-only live system monitor (1400x1020, ~240MB RAM). SOC is the premium live security monitor (1400x1020, ~240MB RAM). ColonyOps is the premium workflow and operator workspace (1280x860, ~260MB RAM, Intermediate to Expert). All five sit on the same backend of 606 generated commands across 26 registered CLI services provided by 25 command-bearing binaries.

Circle is for beginners who want quick guided security setup via an interactive ring, and it is the default. Lite Classic is the main command center for daily operations, and it already carries parallel and sequential command queuing and resizable panels over its 611 dispatchable command presets. ColonyOps targets advanced/power users who need the workflow map, Commander, recipes and Gatekeeper review over the complete 1030-cell surface. Vitals and SOC are the two monitors: Vitals is read-only, and the SOC carries no VPN, DNS, Tor or hardening controls. You can switch between them at any time from the Dashboards button on the left rail, which every dashboard shares, and your last choice is remembered.

AutoShield is guided, beginner-friendly automation: the Kodachi Dashboard's first-boot wizard (Desktop edition) - a single screen with toggleable steps and a countdown timer that runs a preset hardening sequence. workflow-manager is the advanced engine: it chains arbitrary commands with success/fail conditions, regex and JSON-path evaluation, concurrent execution, timeouts and retries. Use AutoShield for fast one-screen setup; use workflow-manager when you need custom, conditional, repeatable multi-step automation.

Yes. The status indicator chips in the top bar (VPN, Tor, KNet, speed, etc.) are draggable. Drag them to reorder the bar to your preference, and the order persists across sessions so your most-used indicators stay front and center.

Yes. Pick a lighter dashboard from the Dashboards button on the left rail, which every dashboard shares: Circle (gamified security ring, the easiest, aimed at beginners) or Lite Classic (the main compact command center for everyday use). Both are far simpler than ColonyOps, and you can switch back at any time. For the full breakdown see the five dashboard modes and how to switch and which dashboard to use.

AutoShield has an auth gate. Non-authenticated users can only run Authenticate (Re-login), Standard recovery, and DNSCrypt (encrypted); identity randomization, routing actions, and premium features require successful Kodachi authentication first. Run the Authenticate step (or the top-bar Auth toggle) before the other steps will work.

Yes. Torrify System + DNS is intentionally off by default because it can conflict with WireGuard on first boot - the VPN must connect first and Tor be torrified separately afterward. Recover Internet is also off by default (not needed when the network is already up), and Harden PC Security is off because it applies system-wide kernel/service changes. The enabled defaults already give maximum shield strength on their own.

On the Terminal edition, AutoShield is the login-shell information screen and interactive menu installed at /etc/profile.d/kodachi-autoshield.sh, exposed as the welcome and shield commands. By default it does NOT auto-run on every login - the profile.d script exits early unless KODACHI_WELCOME_AUTO=1 or KODACHI_WELCOME_FORCE=1 is set; running welcome or shield invokes it on demand (those wrappers set the force flag). If your environment has enabled automatic startup, you can suppress it with the following (e.g. add it to ~/.bashrc); on a non-persistent live session that change will not survive a reboot:

Open Settings > Dashboard > Performance and enable Performance mode, which disables glass blur, glow, and animations at once (glass blur is the most GPU-expensive). For a quick toggle use the clapperboard icon in the top status bar. Also disable Conky in Settings > Dashboard > Conky Control to free CPU.

RAM use depends on the dashboard: Circle is lightest (~230MB), Vitals and SOC are ~240MB, ColonyOps is ~260MB and Lite Classic is heaviest (~300MB) because of its full page set and command queue. The AutoShield first-boot wizard is the lightest surface (~180MB) but it is a guided setup route shown on first boot, not one of the five dashboards. Use Circle or Lite Classic for daily operations and switch to ColonyOps only when you need the workflow map, combining it with Performance mode and disabling Conky to lower overhead further.

It escalates through four configurable threat-response levels set in Settings > Security > Failed Attempt Protection. Level 1 Temporary Lockout auto-unlocks. Level 2 Block Until Recovery locks indefinitely until you use a recovery code. Level 3 System Shutdown immediately powers off (losing RAM data). Level 4 Trigger Panic runs the panic level you choose for it (soft, medium or hard). Choose carefully: Level 3 powers the machine off, and Level 4 cuts the network at every level and is irreversible at hard.

When TOTP is enabled the system generates single-use recovery codes; each works exactly once and they are also required to clear a Level 2 'Block Until Recovery' lockout. They must be stored offline beforehand (printed or in a separate encrypted volume) via Settings > Security > Credentials > Recovery Codes. If you did not save them, recovery requires system-level intervention.

Yes, for the current session or permanently. In the GUI open Settings > Dashboard > Conky Control: 'Enable Conky now' hides or restores the overlay immediately, and 'Start Conky on boot' controls whether it comes back after a reboot. The Lite dashboard diagnostics menu and the keyboard-driven Kodachi Rofi Actions menu (Display & Power) expose the same Conky Enable / Disable / Status controls. From the terminal the underlying commands are, for the session:

And for boot persistence:

Panels out of place after you plug a monitor back in or change the resolution: turn Conky off and on again with any of the controls above, for example Ctrl+K for the Rofi Actions menu, and the panels redraw where they belong. To keep Conky on screen but hide your IP, MAC and other details, use the privacy mask (masking Conky for screenshots).

On one workspace only. There is no setting for this yet, but a small edit does it. The panels are marked sticky, which shows them on every workspace. Remove that mark, then restart Conky from the workspace you want it on:

To move the panels to another workspace later (numbering starts at 0, so 1 means workspace 2):

When Conky restarts, after a login or when its watchdog brings a panel back, it opens on the workspace you are on at that moment, so run the line above again if needed. Edited panel files count as your own: Kodachi's updates keep them as they are and no longer refresh them, so they also miss later improvements to those panels. To undo, put the mark back, which makes them the shipped files again that updates refresh, and restart Conky:

Yes. A screenshot privacy mask replaces sensitive Conky fields such as IP, MAC, country, city, hostname and session IDs with placeholders, then restores the real values when you turn it off. Toggle it from the Lite dashboard diagnostics menu or the Kodachi Rofi Actions menu via Conky Mask Enable / Conky Mask Disable / Conky Mask Status, or from the terminal with:

Use it before sharing screenshots or screen recordings.

Yes - that is exactly what AutoShield is for. Open the AutoShield tab on the welcome screen (or the shield icon in the dashboard header), enable the controls you want, and Arm it. Examples include Connect VPN / Proxy (WireGuard or OpenVPN), Disable Bluetooth, Disable Wi-Fi, Disable Camera, randomize hostname and MAC, and sync the timezone. Pick a countdown and Arm it. An armed AutoShield then runs your chosen actions when the dashboard starts, whichever startup screen you use (Simple, Advanced or Direct), before the launcher continues, so the same privacy posture is applied on every boot with no manual steps. It runs once per boot: closing and reopening the dashboard in the same boot does not run it again.

If clicking the icon does nothing and never shows a window, the dashboard binary is almost certainly failing to start because a system library it needs was removed. Run it from a terminal to see the real error: kodachi-dashboard. A message like this confirms it:

The dashboard is a WebKitGTK application that depends on the GStreamer multimedia libraries; on an installed system these can get pulled out by apt autoremove after you uninstall another app, which silently breaks the dashboard while everything else keeps working.

Fix - reinstall and pin the libraries so they can never be removed again:

1. sudo apt update
2. sudo apt install --reinstall libgstreamer-plugins-base1.0-0 libwebkit2gtk-4.1-0 gstreamer1.0-plugins-base
3. sudo apt-mark manual libgstreamer-plugins-base1.0-0 libwebkit2gtk-4.1-0

The third command marks the libraries as manually installed so future apt autoremove runs leave them alone. Then launch the dashboard normally. If a different library is reported as missing, list everything that is missing with:

Then reinstall those packages the same way. Fresh Kodachi builds pin these libraries by default, so this only affects systems where they were already removed.

The SOC (Security Operations Center) is one of the five dashboards, a premium live security monitor that displays a neural map of host-security telemetry. Open it from the startup launcher, or at any time from the Dashboards button on the left rail that every dashboard shares.

The view shows a central security score core surrounded by ten cluster hubs, VITALS, NETWORK, CONNECTIONS, PROCESSES, THREATS, AUTH, PRIVACY, SYSTEM, AGENTS, and LOGS, each populated with color-coded nodes: green (ok), teal (info), yellow (warn), or red (critical). Hover any node to read its detail. Below the map, four additional panels provide a Score Breakdown, a Top Findings list (tagged with MITRE ATT&CK techniques where applicable), a Privacy Posture summary, and a Live Alert Feed. The toolbar lets you pause the display, adjust the refresh interval, filter by minimum severity, toggle individual clusters, and enable sound alerts for new critical findings.

The SOC carries no VPN, DNS, Tor or hardening controls, but it is not read-only: its WATCHER button enables and disables the host-exposure systemd unit. Vitals is the read-only dashboard. Everything else the SOC shows is telemetry Kodachi already collects. Use health-control or the dashboard action panels to act on anything the SOC surfaces.

Vitals is the premium live system monitor, and the only genuinely read-only dashboard: it watches the machine rather than configuring it. One terminal-style view carries resources, network, connections, the Tor circuit, leak status and cloud readings, all refreshed live. It opens maximized and restores to 1400x1020 at roughly 240MB RAM. Pick it on the startup launcher, or switch to it at any time from the Dashboards button on the left rail that every dashboard shares.

Quick Launch is the picker the Dashboard shows at startup. It lists all five dashboards in two groups: Control (Circle, Lite Classic, ColonyOps), which operate the machine, and Monitor (Vitals, SOC), which watch it. Each card is numbered, so the keys 1 to 5 open a dashboard directly and Enter launches the highlighted one. Dashboards you have not activated are shown locked rather than hidden, and your last choice is remembered for next time. You are not stuck with the choice either: the Dashboards button on the left rail switches dashboards from inside a running session.

It is the eBPF-backed background service behind the SOC dashboard. It records process, network and authentication activity on the machine itself and feeds the SOC neural map, the score breakdown, the top findings list and the live alert feed. The WATCHER button in the SOC arms and disarms it by enabling or disabling its systemd unit, which is the one control in that dashboard that changes system state. Its findings stay on the machine: this is host telemetry, not a cloud service.

The Repository Manager is the desktop window for the Kodachi APT repository; open it from the Kodachi dock, the panel or the applications menu. It browses, installs and removes packages, refreshes the package lists, switches channels and updates the system, so you never have to edit apt sources by hand.

Kodachi publishes three channels: stable, the tested release line most users should stay on; beta, the rolling line that carries the newest builds on their way to the next release; and dev, an access-controlled channel for development builds. Beta usually runs ahead of stable, but not always: right after a stable release the two can match, and for a short time stable can even be newer, which is why the window warns that a move to beta can be a downgrade.

Kodachi 10 updates in place through apt on whichever channel you follow, so there is no separate rolling edition to install. To switch, select the channel under CHANNELS in the sidebar, press Add channel if it is not set up yet, then Move system, which pins every Kodachi package to that channel. Update all installs the updates available on it. Stay on stable for anything you rely on, and use beta when you want to test what comes next (updating without a new ISO).

Kodachi Desktop ships a Cairo dock whose cells are Kodachi actions rather than plain application shortcuts. Clicking a cell runs its action through an authenticating command runner and opens a Kodachi command window with the output, so routing, DNS, identity, maintenance and the Repository Manager are one click away without opening the Dashboard or a terminal. Which cells exist, the order they appear in and what each one does come from the dock layout that ships with the system.

Eleven interface languages ship with the Dashboard: Arabic, German, English, Spanish, French, Hindi, Japanese, Portuguese (Brazil), Russian, Urdu and Simplified Chinese. Arabic and Urdu are laid out right-to-left. The language catalogs are installed alongside the Dashboard, so switching language needs no download and works offline.

Cairo Dock's Themes tab replaces the entire current theme folder inside your home directory, and the Kodachi dock cells live in that folder as launchers, so picking another theme takes every one of them with it. Nothing is damaged system-wide and nothing needs reinstalling. The dock only has to be rebuilt inside your own account.

Full restore, the default look and every Kodachi icon back. Open a terminal as your normal user and run these five lines in order. Do not put sudo in front of them: the dock belongs to your user account, so under sudo you would rebuild root's dock and your own screen would not change.

• systemctl --user stop kodachi-dock
• mv ~/.config/cairo-dock ~/.config/cairo-dock.broken-$(date +%F)
• cp -a /etc/skel/.config/cairo-dock ~/.config/cairo-dock
• kodachi-dock-build build
• systemctl --user restart kodachi-dock

The fourth line reports how many sub-docks, action cells and separators it wrote, and the dock returns the moment you run the fifth. Your previous configuration is kept as ~/.config/cairo-dock.broken-<date>, so nothing is thrown away and you can go back to it.

If you actually like the new theme and only want the Kodachi icons back, run just these two lines instead. Your theme stays exactly as you set it, only the dock cells are rebuilt.

• kodachi-dock-build build
• systemctl --user restart kodachi-dock

Reinstalling Cairo Dock through apt does not fix this. The change is in your own home directory and no package owns anything there, and the Kodachi dock layout and the default theme are part of the system image rather than a package, so removing and reinstalling rewrites neither of them.

Yes. Open the dashboard's Settings → Display. The Interface size slider scales the whole window (also Ctrl and +, Ctrl and -, and Ctrl and 0 to reset), and Text size changes only the text. The same page has:

• Secondary text: Standard or Brighter, for the dimmer descriptions and status words.
• Label font: Monospace or Same as text, so labels use the same clean font as their values.
• Corner style: Square, Standard, Rounded or Extra round.
• Actions page layout: Compact or Comfortable.
• Keyboard focus outline: Standard or Strong, and Scrollbars: Thin, Standard or Wide.
• Security card in the side rail: Show or Hide, plus visual effects and a live preview.

A reset button puts everything back. These options arrived in the October 2026 updates; if your Settings has no Display page, update first (updating without a new ISO).

For the rest of the desktop, including the panels and the file manager, use XFCE's own settings: Appearance → Fonts for the font size and DPI, and Display for resolution and scaling (a missing monitor resolution). If the dashboard feels slow rather than small, see making the dashboard faster.

No, not system-wide. The two lines answer different questions. Tor says whether the Tor service is running, and a pair such as (3/5) beside it shows how many of your Tor instances are running out of how many exist. Torrified, two rows below it, says whether all of your system's traffic is routed through Tor, and Off means it is not. The dashboard says the same thing in the Tor chip's tooltip: Running (not routed through Tor).

To send everything through Tor, torrify: press Torrify in the dashboard, or from a terminal:

Torrified turns On at the next panel refresh, within about 20 seconds. Until then, only applications you point at a Tor SOCKS port yourself use Tor (which ports Tor listens on). To undo it, detorrify (Tor on top of a VPN covers layering it over a tunnel).

No. The dashboard checks your plan with Kodachi's service and unlocks the features that plan includes. When it cannot reach the service, it keeps the last confirmed answer for about half an hour; after that, or when the dashboard starts while you are offline, it falls back to the Free view and shows a padlock on everything Free does not include. Nothing changed on your account.

Once you are back online the padlocks go away by themselves at the next check, within about ten minutes. If your online sign-in also ended while the connection was down, sign in again with Sign in on the left rail (getting signed in). If the connection does not come back, run the network recovery:

What each plan includes is in what Premium adds.

KAICS (Kodachi AI Command Intelligence System) is a suite of local-first AI binaries that turn plain-English requests into real Kodachi and Linux commands. You type something like "am I leaking my IP" or "rotate my tor circuit" and it classifies your intent and runs the right tool. It also handles model training, learning from feedback, scheduling, system monitoring, and policy-enforced agent orchestration. The goal is to turn Kodachi from a manual toolkit into an intelligent, self-improving security assistant.

No. The AI is offline-first by design. The built-in TF-IDF classifier and the local ONNX semantic models run entirely on-device with no network calls, and local GGUF models (Mistral.rs) also run fully offline. You only reach the internet if you deliberately pick a provider-backed engine such as GenAI pointed at a remote provider, or Claude CLI. With the default and local engines, Kodachi AI works with no connectivity at all.

By default, no. All inference and policy evaluation run locally - TF-IDF, ONNX semantic matching, the ONNX intent classifier, and local GGUF models never leave your machine. The system only sends data off-device if you explicitly choose a provider-backed engine (for example GenAI configured against an external provider, or Claude CLI). Privacy-first local processing is the default behavior, and provider routing is always opt-in.

Kodachi exposes a tiered engine stack: TF-IDF statistical matching (built-in, zero setup), ONNX semantic embedding and an ONNX intent classifier, Mistral.rs running local GGUF models, GenAI/Ollama (local Ollama or a configured provider), a legacy local LLM path (deprecated, superseded by Mistral.rs), and Claude CLI. The system auto-routes across the local and provider tiers, falling back gracefully if a higher tier is not installed.

Run fully locally with no network: TF-IDF, ONNX semantic, ONNX intent classifier, and Mistral.rs (local GGUF). Network-capable: GenAI/Ollama is local if pointed at a local Ollama instance but reaches out if configured against a remote provider; Claude CLI always calls Anthropic's service. The default automatic routing only uses the local tiers plus the legacy local LLM - Claude CLI is never part of automatic fallback and must be selected explicitly.

It works immediately. ai-cmd ships with built-in TF-IDF and 350+ pre-configured intent patterns covering Kodachi services, Linux commands, SSL/TLS, network diagnostics, privacy checks, and hardware - no model download, no training, no configuration. Downloading the ONNX model and training is an optional one-time step that improves accuracy from roughly 60% (TF-IDF) to around 85-90% (semantic/classifier).

Yes. The Mistral.rs engine runs local GGUF models entirely on-device with streaming, tool calling, and broad model-architecture support. You download a GGUF model, with profiles like Qwen2.5-1.5B/3B or Phi-3.5-mini, for example with:

Then run queries with --engine mistral. Nothing is sent off the machine when you use this path.

Yes, via the GenAI tier. Install Ollama, pull a model, and run:

When pointed at a local Ollama instance this stays fully local and privacy-safe; the same GenAI path can also target external providers if you configure it that way. It is opt-in - you must explicitly select the genai engine, it is not used by default.

The package includes only the essential ONNX models (about 152 MB) for the fast-path tiers - the custom Kodachi intent classifier, its tokenizer and label files, and the semantic embedding model. GGUF/LLM models for the higher reasoning tiers are not bundled, to keep the package light. You download them on demand with:

The engine falls back gracefully to whatever tiers are present.

Only a CPU. No GPU, NPU, CUDA, or special hardware is required, and it runs identically on bare metal, in VMs, and in containers. TF-IDF-only needs about 128 MB RAM and 20 MB disk; ONNX plus Mistral.rs is comfortable around 512 MB RAM and ~250 MB disk; running the full stack with large GGUF models wants roughly 4 GB+ RAM and 3 GB+ disk. Any x86_64 CPU works at every tier.

Speed and accuracy scale with the tier. TF-IDF answers in under 1 ms at roughly 60% accuracy; the ONNX semantic/classifier models run in about 5-10 ms at 85-90%; local GGUF models (Mistral.rs) take a few hundred milliseconds with strong accuracy; Claude CLI is around a second at the highest accuracy. The fast-path ONNX intent classifier handles roughly 80% of queries in under 5 ms, routing only complex queries to slower reasoning engines.

Plain-English planning and preview (dry-run) work without elevated privileges. Live command execution through ai-cmd requires a valid online-auth state. sudo is only needed for specific privileged operations - for example training and learning steps (ai-trainer, ai-learner), the daemons (ai-monitor, ai-scheduler), and any underlying command that itself needs root. Day-to-day querying and preview do not need sudo.

The KAICS binaries (ai-cmd, ai-trainer, ai-learner, ai-admin, ai-discovery, ai-scheduler, ai-monitor, ai-gateway) ship pre-installed in the unified binary pack on both editions. The AI models and natural-language workflows are an optional add-on you enable on demand: on the Terminal edition you enable the KAICS workflows when needed, while Desktop has them wired into the dashboard out of the box.

ai-gateway is the machine-facing command API that AI agents and automation use instead of calling Kodachi binaries directly. It provides unified service discovery, machine invocation hints, deterministic JSON-argument execution, and - most importantly - a policy firewall that classifies every command by risk and blocks dangerous operations unless they are explicitly authorized. It is the safety net between AI agents and your system.

An approval ticket is a human-issued, time-limited authorization for a specific dangerous operation by a specific agent. An operator runs ai-gateway approve issue for, say, block-internet with a TTL (e.g. 600 seconds), and the agent must then present its verified identity plus that ticket to execute. Once the ticket expires the authorization is gone, so even a trusted agent cannot run destructive commands on its own without a fresh human approval.

The gateway recognizes a fixed set of verified agent IDs: anonymous, nullclaw, agentzero, openclaw, picoclaw, nanoclaw, claude-code, gpt, gemini, and open-interpreter. Each agent has its own capability profile, and trusted batch mode requires a per-agent token.

ai-cmd is the human-facing natural-language CLI of KAICS. You ask in plain English ("is digi77.com ssl valid?", "who is on my network", "how private am I") and it classifies the intent and runs the matching Kodachi or Linux command. It supports preview/dry-run, interactive REPL mode, real-time streaming, native tool calling, and a feedback mechanism so you can correct misclassifications.

ai-cmd is the human-facing interface - you talk to it in natural language and it figures out and runs the command. ai-gateway is the machine-facing policy and execution layer that AI agents and automation use, with strict risk controls and JSON arguments. ai-cmd actually routes its live executions through ai-gateway for policy validation by default, though you can bypass that with --no-gateway for long-running commands.

ai-trainer manages machine-learning models: it downloads the ONNX semantic model, trains the intent classifier from command metadata, validates accuracy, snapshots, and exports models. ai-learner is the continuous-improvement engine: it processes accumulated user feedback and usage patterns to adjust the model so classification accuracy improves over time. All training and learning happen locally with no cloud dependency.

Their databases are created on your machine; none ships pre-built. sudo ai-trainer train writes data/embeddings.db (and ai-trainer builds it from the bundled training data by itself when it is missing), ai-cmd creates data/learning.db on its first query, and ai-learner learn creates data/kaics.db. Until then a status saying the database was not found is normal: ai-learner status reports it as not initialized and tells you to run some ai-cmd queries and then ai-learner learn.

Training data for ai-trainer is written by hand; it is not collected from your usage. The exact format is on the ai-trainer page, with ready-made starter files: training-data.json and test-cases.json. The ai-learner page covers the learning side, including doing it from the Lite dashboard.

These are the three daemons. ai-discovery is a binary watcher and auto-indexer that detects new Kodachi binaries and makes their commands available to ai-cmd. ai-scheduler is a cron-based task scheduler for automating learning cycles, security checks, and maintenance. ai-monitor proactively watches system and security state (working with health-control, tor-switch, dns-leak) and raises suggestions when it detects issues.

ai-admin is the maintenance toolbox for the AI system. It manages the SQLite database that stores training data, feedback, predictions, and learning history, and provides diagnostics, integrity checks, backup and restore, performance tuning, index rebuilding, and cleanup. You use it for weekly maintenance and for recovery if the AI database is ever corrupted.

The binaries form a closed improvement loop. ai-discovery indexes available binaries; ai-trainer trains the model from that metadata; ai-cmd answers queries and collects feedback when it gets something wrong; ai-learner processes that feedback to adjust model weights; and ai-scheduler can automate the whole cycle on a schedule while ai-monitor feeds in system state. Each pass makes intent classification more accurate without sending anything to the cloud.

It is heavily guarded against that. Emergency intents (panic, block-internet, wipe) require elevated classifier confidence, and a cryptographically signed AI policy file sets per-category confidence thresholds and an approved-tool allowlist. On top of that, when execution goes through ai-gateway, destructive commands are blocked unless a human-issued approval ticket is supplied (see Does Kodachi classify AI-agent commands by risk and require human approval for dangerous ones?). Low-confidence or unknown queries route to slower analysis or human review rather than executing.

Yes. ai-gateway carries an embedded catalog of Kodachi service commands and classifies every one into a three-tier risk model: Passive, Active, and Dangerous. Passive commands run freely, while Active and Dangerous commands are blocked unless a human-issued approval ticket is supplied via --approval-ticket. A policy firewall with allowlist enforcement, workspace path confinement, per-agent rate limiting, and a full audit trail back this up so an AI agent cannot quietly run destructive operations. Dry-run validation is always allowed, so an agent can plan first and only execute once the approval gate is met.

Kodachi ships with 14 routing protocols through the routing-switch binary: WireGuard, OpenVPN, Tor, Xray-VLESS, Xray-VLESS-Reality, Hysteria2, Xray-Trojan, V2Ray, Shadowsocks, Mieru/Mita, Dante (SOCKS5), Xray-VMess, AmneziaWG, and OpenVPN over Cloak. The last two are censorship transports for networks that fingerprint VPN protocols by signature rather than general-purpose upgrades, and neither is picked by accident: plain auto-select ranks twelve and skips both, so pass --prefer-obfuscated to bring them in, so read what AmneziaWG is and what OpenVPN over Cloak is before reaching for them. Xray-VMess is kept only as a legacy fallback and carries the lowest security score of the fourteen. They are pre-configured from your authentication card, so there is nothing to set up manually - it picks the best one when you run:

No. Once you authenticate with online-auth, routing-switch automatically fetches your "card" containing all server details and configures every protocol for you. The documentation explicitly lists this as "Zero Configuration" - protocols are pre-configured from authentication cards. You just choose a protocol, or let auto-select choose the best-scoring one.

By Kodachi's own hardcoded scoring, WireGuard is the top choice on all three counts: it has the highest security score (98), highest reliability (98) and the highest speed score (95). So the common guess that OpenVPN is the most secure, Hysteria2 the fastest and WireGuard merely a middle option is not what the source says. Hysteria2 is the second-fastest (speed 94, just behind WireGuard) and is the best choice on unreliable/restrictive networks; OpenVPN is very reliable (96) but slower (~70-80% of line speed vs WireGuard's 90-95%). The honest takeaway: don't memorize a ranking - run the selector, which weights speed 30%, reliability 25%, security 25%, plus measured latency and bandwidth, and picks the best overall protocol for your current network:

AmneziaWG and OpenVPN over Cloak do not belong on this ranking at all. They are not chosen for a speed or security position; they are chosen for one specific network condition, a network that identifies and blocks VPN protocols by signature. On a network that is not doing that, both are strictly worse than the plain parent protocol.

Yes. tor-switch can run multiple Tor instances with three native kernel-level load-balancing modes: Round-Robin (each new flow goes to the next instance in sequence via numgen inc mod N, so every new connection gets a different exit IP - good for general use and IP rotation), Weighted (traffic distributed by per-instance weights you assign, e.g. tor1 50%, tor2 30%, tor3 20% - good for prioritizing faster/more reliable instances), and Consistent Hashing (same source IP always maps to the same instance via jhash ip saddr mod N - good for banking, streaming and social-media sessions that block frequent IP changes). For application-level balancing it can also generate HAProxy configs with roundrobin or leastconn algorithms plus health checks and stats.

No. dns-switch ships with an extensive built-in database of vetted DNS servers categorized by security level (reputable, normal/standard, encrypted, and emergency fallback). You can switch to a random secure server with:

Health-check servers with:

Or refresh the list from remote sources with:

You can also verify DNS behavior with the online Kodachi DNS Leak Test at /tools/dns.html.

Yes, two forms. DNSCrypt is fully integrated - enable it with:

DNS queries are then encrypted to a resolver on 127.0.0.1, preventing your ISP or an on-path attacker from seeing the sites you visit. You can also layer DNSSEC signature validation on top:

And DoH (DNS-over-HTTPS):

Separately, when the system is torrified, DNS is resolved through the Tor network (Tor DNS), so lookups inherit Tor's anonymity. The DNS category list also includes DNSCrypt and DoH servers for encrypted queries.

Yes, in two ways. (1) After connecting routing-switch, run:

Then point selected clients at socks5://USER:PASS@YOUR_IP:30050 (the port is selected from 30050-30054). (2) Generate a QR code for a compatible client, for WireGuard or a supported Shadowsocks, V2Ray, or Xray variant:

The Terminal Server edition can act as a managed SOCKS gateway, but only clients and applications configured for it follow that route. Verify IP and DNS behavior on every client.

Yes - and with routing-switch this is the only way to use the remote Tor route. Kodachi's remote Tor is VPN-only by design: connect any Kodachi protocol first - WireGuard, OpenVPN, or a proxy protocol (Shadowsocks/V2Ray/Xray/Hysteria2/Mita) - then layer Tor on that tunnel, keeping it as the underlay, no --force needed:

A standalone connect tor with no tunnel is refused with an on-screen explanation, because the worker Tor SOCKS port is never exposed on a public IP: a publicly reachable Tor SOCKS port gets abused as an open proxy. The worker Tor binds only to the VPN networks, so it is reachable only after you join the Kodachi network. More broadly, tor-switch supports system-wide torrification on top of any existing VPN - WireGuard, OpenVPN, Hysteria2, Shadowsocks, V2Ray or Xray:

And you can build multi-hop chains (e.g. triple VPN + Tor) with workflow-manager.

By design. Running sudo routing-switch connect tor with no tunnel active is refused, because Kodachi's worker Tor SOCKS proxy is never published on a public IP - a publicly reachable Tor SOCKS port is abused as an open proxy almost immediately. The worker Tor binds only to the Kodachi VPN networks, so to use it you first have to be inside the Kodachi network. connect tor layers Tor on top of any active Kodachi protocol - WireGuard, OpenVPN, or a proxy protocol (Shadowsocks, V2Ray, Xray, Hysteria2, Mita) - keeping that protocol as the underlay. Two supported ways: (1) connect any protocol first, for example (or openvpn, shadowsocks, hysteria2...):

Then layer Tor on it:

Or (2) the easier route for WireGuard/OpenVPN - after connecting, point your browser's SOCKS5 proxy at 172.16.0.1:9050 (over OpenVPN) or 10.0.0.1:9050 (over WireGuard), with no connect tor step at all.

Yes. Rotate Tor exit nodes/IPs through tor-switch, and switch routing protocols on demand with:

On Desktop the dashboard has one-click Randomize MAC, Randomize Hostname and Randomize Timezone actions plus Tor exit-node country rotation. Verify the new identity with ip-fetch (full geolocation), or confirm the Tor IP with:

And confirm DNS follows with:

See the active protocol and connection state (add --json for structured output) with:

See exactly which DNS/resolver endpoints the active route uses with:

ip-fetch shows the resulting public IP and geolocation, and this confirms whether Tor is in the path:

On Desktop, the dashboard and Conky overlay display the live routing/DNS state.

Yes. Beyond classic VPNs it ships censorship-resistant transports: Shadowsocks, V2Ray, the Xray family (VLESS, VLESS-Reality, Trojan, VMess), Hysteria2 (QUIC-based, good for unreliable/restricted networks) and Mieru/Mita. You can test which ones work in your environment with:

Then connect to the best survivor, for example:

Tor and HAProxy-balanced multi-instance Tor add further reach.

Two protocols exist specifically for a network that fingerprints and blocks VPN protocols by signature. AmneziaWG:

OpenVPN over Cloak:

Escalate in this order:

1. Try plain WireGuard or OpenVPN first. On a network that is not inspecting protocols they are faster and simpler than anything below.
2. If the tunnel fails the same way every time on one specific network while the same credentials work elsewhere, that repeatable single-network failure is the signature of protocol blocking. Move to AmneziaWG, which keeps WireGuard speed while removing the fixed handshake fingerprint.
3. If UDP itself is blocked rather than merely fingerprinted, AmneziaWG cannot help, because it is still UDP. That is when OpenVPN over Cloak is the right answer: it runs over TCP and the outer connection looks like an ordinary browser HTTPS session.

Both are the wrong choice on a normal network. They solve exactly one problem, protocol identification by the local network, and neither is a substitute for Tor: they hide what protocol you are speaking from the local network, they do not hide who you are from the endpoint.

System-wide, not just the browser. routing-switch routes the whole system through the tunnel, using native kernel routing for WireGuard/OpenVPN, redsocks transparent proxy for Tor, and a shared TUN interface (tun2socks) for the proxy protocols. tor-switch can also torrify the entire system at the firewall level (nftables/iptables) on top of the VPN routes. Excluded local ranges stay local. WireGuard and OpenVPN replace the default route; the tun2socks-based protocols keep the original gateway as a high-metric recovery route, so traffic can leave through it if the tunnel process dies. Arming the kill switch only raises a flag and watches nothing. Every panic level starts with the network step: it sets the IPv4 firewall to drop everything, stops NetworkManager, Tor and OpenVPN, and takes every network interface except loopback down, so IPv6 stops with the links (no IPv6 firewall rule is added; the live boot entries disable IPv6 anyway). Triggering the kill switch runs panic level medium, which also terminates running processes, clears memory caches and the clipboard, unmounts removable devices and locks the screen. Check the route status after any interruption.

Yes. Use the tor-switch Consistent Hashing load-balancing mode:

The same source IP then always maps to the same Tor instance via jhash ip saddr mod N, so a given device keeps a stable exit IP per traffic type. The docs specifically recommend this mode for services that block frequent IP changes such as banking, financial services, streaming platforms and social-media sessions.

Yes. The Desktop dashboard includes a built-in VPNGate public-server browser under Essentials > Actions > Connection > VPNGate: it fetches and caches live public OpenVPN servers from the VPNGate API, lets you filter by country and sort by speed/ping/score/sessions, and connect in place or export .ovpn profiles. There is also a guided Fix Internet Wizard that pre-checks routing, DNS, DNSCrypt and torrify state before repairing connectivity.

Yes. routing-switch supports metric routing with private-network exclusion:

This keeps LAN access (e.g. pinging 192.168.1.1 still works) while routing internet traffic through the VPN. In metric mode, the original clear route may remain usable if the VPN drops. Recheck routing status and explicitly recover or reselect the protected route before resuming. Local/private ranges like 192.168.0.0/16, 10.0.0.0/8 and 172.16.0.0/12 are excluded from the proxy by default.

Yes. tor-switch supports multiple Tor instances, and you can create regional instances each pinned to a different exit country, then run them all simultaneously:

And verify with:

Combined with the load-balancing modes this lets you distribute traffic across several countries' exit nodes at once.

Yes. routing-switch can export configurations with:

It can also show the current config (showconfig), output it as a URL (showconfigurl), or as a scannable QR code (showconfigqr) for WireGuard, Shadowsocks, V2Ray and Xray variants. This lets you move a working profile to a phone or a third-party client without re-entering credentials.

Per the documented performance figures, WireGuard reaches about 90-95% of your line speed and OpenVPN about 70-80%, while Tor is typically only 1-10 Mbps because of its multiple relay hops. Connection setup is roughly 2-10 seconds depending on protocol, VPN protocols use ~40MB RAM and proxy protocols ~60MB. If Tor is too slow, multi-instance load balancing across several Tor instances improves throughput.

Yes, it is strongly discouraged. In a Tor -> VPN chain the Tor entry/guard node still sees your real IP, your ISP can still detect Tor usage, you lose access to .onion sites, performance is severely degraded, and trust shifts entirely to the VPN provider who can see your activity. Use VPN -> Tor instead: connect the VPN first, then torrify on top of it.

No, this is expected under load-balanced torrification. Kodachi runs multiple independent Tor instances in parallel, each with its own circuit and exit relay, usually in different countries, and nftables spreads outgoing TCP flows across them - so different apps legitimately leave through different Tor exits at once. This per-flow IP isolation is the point of multi-instance torrification and breaks 'one user = one exit IP' linkability. A direct external connection that is not to a local Tor port, however, is a genuine leak.

You are using a per-flow load-balancing mode (Round-Robin or Weighted) that varies the exit IP. Switch to Consistent-Hashing mode, where on a single workstation all apps share one source IP and hash to one instance, giving an effectively stable exit IP. Alternatively drop load balancing and use single-instance torrify for one stable IP and shared circuit.

It is a deliberate design choice: the generator uses two independent seeds (one for non-DNS TCP, one for DNS) so the two traffic classes distribute differently across the instance pool. Each is independently stable over time, so logged-in TCP sessions still see a stable exit. If you need TCP and DNS to share one exit, drop load balancing and use single-instance torrify.

No. The nftables/iptables torrification rules exclude localhost (127.0.0.0/8) from the TransPort redirect, so traffic FoxyProxy sends to a local Tor SOCKS port stays local and reaches Tor directly rather than being redirected through TransPort a second time. The result is a single Tor layer, not double routing.

This is expected, not a broken connection. Tor only carries TCP, so ICMP ping cannot traverse a torrified host and will always appear to fail even when HTTP/TCP connectivity is fine. The Fix Internet Wizard deliberately weights the HTTP connectivity check over the ping check when the host is torrified - trust the HTTP result.

Yes. The easiest path is the Mobile manager tab in the dashboard (see How do I use the Mobile manager tab?), which lets you copy share links, scan QR codes, and export configs for every active protocol in one place without any CLI. For CLI access, write the config to a file with (or shadowsocks, v2ray in place of wireguard):

Or print a scannable QR code with:

Scan the WireGuard QR with the official WireGuard app on iOS/Android; for Shadowsocks, V2Ray and Xray variants use a V2RayNG/Shadowrocket-class client. Run this with no protocol to export all of them at once:

None of these export/show commands need sudo.

Each protocol row in the Mobile manager tab shows an "Open in" app strip where every recommended client appears once with its own iOS and Android store links, plus a tooltip; that in-app list is always authoritative. The canonical picks per protocol:

• WireGuard, iOS: WireGuard (official), Hiddify, Streisand, Shadowrocket ($2.99). Android: WireGuard (official), Hiddify, NekoBox. (Happ does NOT support WireGuard.)
• OpenVPN, iOS: OpenVPN Connect. Android: OpenVPN Connect, OpenVPN for Android (open-source). No QR (config too large), use Export and import the .ovpn file.
• Shadowsocks, iOS: Shadowrocket ($2.99), Outline, RocketTunnel (free, incl. SS2022), Streisand, V2Box, Happ, Hiddify. Android: V2RayNG (GitHub), Outline, RocketTunnel (free, incl. SS2022), Hiddify, V2Box, NekoBox, Happ.
• V2Ray (VMess), iOS: Shadowrocket, V2Box, Streisand, Happ, Hiddify. Android: V2RayNG (GitHub), V2Box, Hiddify, NekoBox, Happ.
• Xray (VLESS / VLESS-Reality / Trojan / VMess), iOS: Happ, V2Box, Streisand, Hiddify, Shadowrocket. Android: V2RayNG (GitHub), V2Box, Hiddify, NekoBox, Happ. (Each Xray variant is its own row using the same clients; the plain VLESS-TLS row also lists RocketTunnel, which imports plain VLESS but not Reality / Trojan / VMess.)
• Hysteria2, iOS: Happ, Hiddify, Streisand, V2Box, Shadowrocket. Android: Hiddify, NekoBox, V2RayNG (GitHub), Happ, V2Box.
• Mita (Mieru), iOS: Shadowrocket ($2.99, mieru added 2026). Android: NekoBox + mieru plugin, or Hiddify. (Happ / Streisand / V2Box do not support mieru.)
• Dante (SOCKS5), iOS: Shadowrocket, Happ, Streisand, V2Box. Android: NekoBox, V2Box, Hiddify, or the native system SOCKS proxy settings.
• Tor, iOS: Onion Browser. Android: Orbot. Point any app with a SOCKS field at the printed host:port.
• Private DNS, no app needed: paste the host:port into iOS Settings > DNS or Android Settings > Private DNS (Android 9+), or use Intra on Android.

Universal multi-protocol clients (Hiddify, Happ, NekoBox) cover most protocols at once, so if you already have one installed you usually do not need a per-protocol app.

Sign in first: the tab is locked until you authenticate. Each active protocol row then offers four actions: Copy share link (copies the URI such as vmess://… or wg://… to your clipboard), QR (shows a scannable QR code in a modal), Export (writes the config file to disk), and Config (displays the raw config text inline). A tooltip on each row suggests the recommended mobile app for that protocol. Four bulk actions at the top let you open all QR codes in a gallery, export all configs at once, save all QRs as PNGs, or copy all share links in one click. An external-provider section covers Riseup and VPNGate bulk exports with the same actions, and a raw authentication card viewer at the bottom shows the full card JSON for manual imports. Available in the Welcome screen and in both the Lite and Advanced dashboards.

Print the current protocol's configuration as a URL with:

Or render it as a QR code in the terminal with:

Add a protocol name to target a specific one, for example:

To just display the configuration:

All four of these are read-only and do not require sudo. QR works with WireGuard, Shadowsocks, V2Ray and the Xray variants (xray-vless, xray-vless-reality, xray-trojan).

Yes. routing-switch has built-in VPNGate integration providing 100+ public VPN servers that require no account or authentication, so you can route traffic even without your own VPN subscription. It can also export those servers with:

Or all of them with:

Both are read-only and do not require sudo. Combined with automatic protocol scoring and selection, this gives you a working tunnel out of the box.

Yes. The External VPN Providers tab (Globe icon on the dashboard sidebar) catalogs 12 third-party providers: VPN Gate, Riseup, NordVPN, IVPN, PIA, Surfshark, AirVPN, Mullvad (WireGuard-only since 2026), Windscribe, ProtonVPN, ExpressVPN, TorGuard, plus a "custom" pseudo-provider for pasted configs, 13 catalog entries in all. Account-free pools such as VPN Gate and Riseup connect without a provider account; that does not guarantee anonymity. Paid providers store credentials at ~/.config/kodachi/vpn-credentials.json mode 0600. Set them once via the per-provider editor, then click a server row to connect. ProtonVPN, ExpressVPN, and TorGuard have no public auto-fetch API; their cards link to the provider site so you can download an .ovpn file and import it.

Any other provider works the same way as long as it hands out standard OpenVPN or WireGuard configuration files: import one through the Custom card (pasting your own config). Kodachi connects with its own engine so that the kill switch, DNS protection and Tor routing stay in control. A service that offers no such files cannot be added: NymVPN, for example, signs in with rotating anonymous credentials and published no configuration files as of October 2026. Its own app can run on Kodachi once you hand DNS over to it (third-party VPN apps), but then its own kill switch and leak protection do the work, and Kodachi's checks do not cover that tunnel.

Yes. The Import config widget at the top of the External VPN Providers tab auto-detects the protocol from any pasted body. It handles OpenVPN .ovpn, WireGuard .conf, Shadowsocks JSON, V2Ray JSON, Hysteria2 YAML, and the URI schemes vmess://, vless://, trojan://, ss://, hysteria2://, tuic://. It also recognizes Clash YAML (proxies: list) and sing-box JSON (outbounds: list) subscriptions: a single paste explodes into N profiles. The Validate button does a dry-run preview (CV-3 draft-validate) so you see the detected protocol, endpoint, and any warnings before committing.

Two ways. Without measuring:

This sorts by provider-reported speed_bps and load, which works well for VPN Gate and AirVPN (which publish those metrics) but less so for others. To use real measured latency, click the Test latency chip in the action bar, or run:

This pings each cached server (ICMP first, TCP-connect fallback) with bounded concurrency and stores latency_ms in the cache. Manual only (never auto-runs), same UX as ip-fetch's manual cache refresh. After a benchmark, connect-fastest prefers measured latency over provider-reported speed.

Yes - but through NetworkManager configuration, not a boot-time MAC-change script. There is no systemd service, live hook, or rc.local that runs macchanger or health-control to change the MAC at startup; those tools are on-demand only (dashboard/menu triggered). The randomization comes from /etc/NetworkManager/conf.d/99-kodachi-mac-randomization.conf: Wi-Fi scans use a random MAC, each Wi-Fi connection uses a per-boot pseudo-random (stable) MAC, and Ethernet gets a fresh random MAC per connection. So the address seen on the network is randomized every boot rather than your burned-in hardware MAC. This applies to NetworkManager-managed Ethernet/Wi-Fi (the normal case); an interface not managed by NetworkManager, or a tool that bypasses it, would still expose the real MAC.

Kodachi randomizes the MAC for privacy via NetworkManager (wifi.cloned-mac-address=stable), so a router that only hands out IPs to provisioned/whitelisted MACs rejects the randomized one. Resetting the MAC by hand does not hold because NetworkManager re-applies the cloned MAC on every connect. The fix is to make that one connection use the real hardware MAC: in the connection settings set Cloned MAC Address = Permanent, or from a terminal run:

then:

Only that network loses randomization; the configured MAC-randomization policy remains enabled for other networks (see how the MAC is randomized at boot). On a live USB this is not saved - reapply each boot or install to disk, where it persists.

Kodachi locks /etc/resolv.conf immutable for DNS-leak protection, which stops third-party VPN clients from writing their tunnel DNS - so Mullvad/ProtonVPN fail to set DNS and their own kill-switch blocks all traffic. Hand DNS over to the VPN client first, then connect.

From the command line:

1. Unlock resolv.conf and pause Kodachi DNS protection:
   sudo dns-switch external-dns --state on
   This is an emergency command, so it needs no online authentication (important when a failing VPN has already cut your internet).
2. Connect your VPN in its app, or from the terminal, for example:
   mullvad connect
   It now sets its DNS and stays connected.
3. When finished, disconnect the VPN, then restore Kodachi-managed, re-locked DNS with:
   sudo dns-switch external-dns --state off
   Check the current state anytime with:
   sudo dns-switch external-dns --state status

From the Dashboard: open Lite Classic → Essentials → DNS Essentials (or Command & Monitor → Command Builder, DNS service), select External VPN DNS, set the state to on before connecting your VPN and back to off when you are done.

Notes: while it is ON, Kodachi's immutable DNS-leak lock is paused, so your VPN client must enforce its own leak protection (Mullvad and ProtonVPN both do). The setting persists across reboots on an installed system; re-run it each boot on the live ISO. Pi-hole cannot be enabled while External VPN DNS is ON because both need to own system DNS. If a VPN client strictly requires systemd-resolved rather than writing resolv.conf, switch DNS mode with:

No, this is normal and expected behavior, not a bug or a leak. The Kodachi Network indicator (also shown as Kodachi Cloud / KNet in the status bar) only checks whether your current public IP is recognized as part of Kodachi's own VPN infrastructure: the dashboard asks the kodachi.cloud service whether your exit IP belongs to a Kodachi node. When you connect a separate VPN such as PIA, your traffic now exits through that provider's server, so your public IP becomes a PIA IP rather than a Kodachi node IP. The check correctly returns false and the indicator goes inactive.

Only one VPN exit can be active at a time, so being connected to PIA and being shown as off the Kodachi network at the same moment is the correct result. To make the indicator active again, disconnect the third-party VPN and route through Kodachi's own VPN/nodes instead. If your third-party VPN client itself refuses to connect or reports "internet blocked", see how to use a third-party VPN GUI like Mullvad or ProtonVPN.

Torrify routes your whole system through Tor on top of your active VPN connection. It works over most Kodachi protocols, but bare system torrify does not work over xray-vless-reality (XTLS Vision) by default. This is a known, by-design limitation of the XTLS Vision flow, not a Kodachi bug.

Root cause. The Reality protocol uses XTLS Vision (flow: xtls-rprx-vision). Vision is designed to detect the TLS handshake inside the tunnel, pad it, and then splice the raw stream directly, bypassing an extra TLS wrapper. Tor relay connections are themselves TLS, so when your system is torrified over Reality, Vision sees Tor's nested TLS handshake as an anomaly, mangles the stream, and Tor gets stuck at roughly 10% bootstrap with unexpected eof while reading / TLS_ERROR on every relay. The Xray-core project closed the relevant issue (#3206) as "not planned" because the behavior is intentional: Vision is built to splice exactly one TLS layer and a second nested TLS layer breaks that assumption.

How it was confirmed. All tests used the same exit server (198.105.112.55). Through that server, switching to xray-vmess (no Vision flow) or WireGuard made Tor bootstrap to 100% and exit through a real Tor IP. Only xray-vless-reality failed. The failure is Vision-specific, not server-specific.

Fix 1: use an obfs4 bridge (works today, verified). obfs4 wraps Tor's traffic in obfuscated, non-TLS bytes. Vision's TLS-in-TLS detection never triggers because there is no TLS handshake for it to find. With an obfs4 bridge configured in Tor Browser, Tor bootstrapped to 100% over a Reality VPN connection and exited through a real Tor node. Configure Tor Browser to use obfs4 bridges (Settings > Connection > Use a bridge > obfs4) and use it on top of your Reality connection. Kodachi is adding bridge support to the system-wide torrify path (sudo tor-switch torrify-system-nftables-dns) so the full system can torrify over Reality via bridges without needing Tor Browser specifically.

Fix 2: switch to a non-Vision protocol for Tor (no bridges needed). WireGuard and OpenVPN use native kernel routing with no TLS splicing involved, so plain system torrify works over both. xray-vmess, Shadowsocks, V2Ray, Hysteria2, and Mita/Mieru also carry no Vision flow, so torrify works over them as well. AmneziaWG and OpenVPN over Cloak carry no Vision flow either, and both keep the native kernel routing of their parent protocol.

Protocol compatibility table.

The underlying reason is XTLS Vision's TLS-in-TLS handling. There is no server-side or client-side configuration that makes plain (non-bridged) Tor survive through a Vision-enabled Xray path. You must either drop Vision (switch protocol) or use an obfs4 bridge.

Yes, on the paid plans. Open the License Portal, paste your license key, and the "Your Nodes" panel lists every managed node your license can reach. Tick the ones you want to use and save. The Free tier has a single shared node and no portal login, so there is nothing to choose there.

What each plan can select. Access runs downward only, never upward:

• Premium: your premium nodes, and optionally the free node.
• Custom: your own dedicated node or nodes, and optionally the premium nodes and the free node.
• Free: the free pool only. A free device can never reach a paid node, whatever it asks for.

Your default does not change unless you change it. With no selection saved, Premium keeps picking at random across the premium nodes and Custom keeps using its own isolated node, exactly as before. A lower tier is only ever used if you deliberately tick it, so the free node never becomes part of a paid default.

What the portal shows you. Each node carries its country, exit IP, a stable name (Premium node 1, Your dedicated node), how busy it is, and which one is serving your device right now. The panel also states your package, what "default" means for it, what you currently have saved, and your live route, so there is no guessing about which server you are on.

If your chosen node is full. A switch controls this. Left on (the default), you are moved to another node inside your own plan when your selection has no capacity, and you stay connected. Turned off, the connection is refused instead, so you are never quietly moved to a node you excluded. Fallback never crosses into a tier you did not select.

When it takes effect. On the next connection from that device. A session that is already running keeps the node it was given, so saving a selection never cuts you off mid-use.

The privacy trade-off, stated plainly. Pinning one node keeps your exit address predictable, which is useful when a service you depend on is sensitive to changing IPs. It also makes your sessions easier to link to each other, because you always leave from the same address. Leaving the choice open spreads you across the pool and gives you a larger crowd to blend into. That is why random across your plan remains the default.

Multiple devices and support overrides. The selection belongs to the license key, so every device activated on that key follows it. Support can set or lock a selection on request, for example to keep an organisation on one jurisdiction; while a lock is in place the portal shows the choice as read-only.

AmneziaWG is WireGuard with the handshake disguised. A stock WireGuard connection opens with a fixed 148-byte initiation packet, which deep packet inspection fingerprints trivially: a censor does not have to break the crypto, it only has to recognise the shape of that first packet and drop the flow. AmneziaWG sends junk packets before the real handshake and randomises header fields, so that signature is gone.

Connect with:

What it costs you in speed: essentially nothing. It keeps WireGuard's ChaCha20-Poly1305 crypto and the same UDP data path, so steady-state throughput is essentially WireGuard's. The obfuscation is spent on connection setup, not on every packet. That is what the design implies; no measured Kodachi throughput figure has been published for it, so treat it as a design property rather than a benchmark.

Three things that will confuse you if nobody warns you.

• The interface is awg0, not wg0.wg show reports nothing at all while the tunnel is up and perfectly healthy, because it is looking at the wrong interface. Use this instead:
  sudo awg show
• It requires the amneziawg kernel module. Without that module the connection cannot come up.
• It is not interoperable with a stock WireGuard peer in either direction. An AmneziaWG client cannot talk to a plain WireGuard server, and a plain WireGuard client cannot talk to an AmneziaWG server.

On mobile, the official AmneziaVPN app is the only client that speaks it. Ordinary WireGuard apps cannot import an AmneziaWG configuration.

When it is the wrong choice. AmneziaWG solves exactly one problem: a network that identifies and blocks VPN protocols by signature. On any network that is not doing that, plain WireGuard is the better answer and AmneziaWG is strictly worse. It is also not a substitute for Tor: it hides which protocol you are speaking from the local network, it does not hide who you are from the endpoint. And because it is still UDP, it cannot help on a network that blocks UDP outright, which is what OpenVPN over Cloak is for.

OpenVPN over Cloak is OpenVPN wrapped in the cbeuw/Cloak pluggable TCP transport. The outer connection looks like an ordinary browser HTTPS session to a real decoy site. Anything that probes that port without a valid Cloak key is served the decoy site instead of a VPN handshake, so an active prober sees a working website rather than evidence of a tunnel.

Connect with:

Why the .ovpn file appears to point at your own machine. A separate ck-client process holds the real TCP connection to the server, and the OpenVPN configuration deliberately points at 127.0.0.1. That is intentional, not a broken config: reading a server address or port out of the .ovpn text gives you the loopback port and never the real endpoint. The Cloak client configuration is where the actual destination lives.

What it costs you: TCP inside TCP. Your applications already speak TCP, and here that TCP rides inside Cloak's TCP connection. Once the underlying link starts losing packets, both layers retransmit and back off independently, so the degradation is non-linear rather than proportional to the loss rate. On a clean link the overhead is modest; on a lossy one it is severe. No measured throughput figure has been published for this protocol, so plan around the design implication and test it on your own link.

Desktop only in practice. Cloak runs as a separate transport process alongside OpenVPN, and mainstream mobile OpenVPN apps cannot launch that helper process, so there is no straightforward phone or tablet setup.

When it is the wrong choice. Cloak solves exactly one problem: a network that identifies and blocks VPN protocols by signature. On any network that is not doing that, plain OpenVPN or WireGuard is faster and simpler and this is strictly worse. It is also not a substitute for Tor: it hides which protocol you are speaking from the local network, it does not hide who you are from the endpoint. Escalate in order: plain WireGuard or OpenVPN first, then AmneziaWG if the tunnel fails the same way every time on one specific network while the same credentials work elsewhere, and come here when UDP itself is blocked rather than merely fingerprinted, because AmneziaWG is still UDP and cannot help with that.

Nothing is wrong with your configuration: the AmneziaWG kernel module cannot load on those three boot entries, and the same is true on any entry if UEFI Secure Boot is enabled in firmware. AmneziaWG is delivered as an out-of-tree DKMS module (amneziawg), signed with a certificate created during the Kodachi build that no machine trusts. Kernel Lockdown (confidentiality) and Full Hardening set module.sig_enforce=1, and Full Hardening and Maximum Privacy set lockdown=integrity; each of those makes the kernel refuse the module. A manual sudo modprobe amneziawg then fails with Key was rejected by service or Required key not available, and lsmod | grep amneziawg comes back empty.

The fix is to reboot into an entry that does not enforce signatures: Kodachi Live, Persistent, Encrypted Persistence, CPU Hardened, or any Advanced entry such as DMA Protection or Full RAM mode. Forensics is no longer on that list: it gained lockdown=integrity on 2026-09-04. Plain WireGuard is unaffected on every entry, because its module is built into the Debian kernel and carries Debian's own signature, so if you need a hardened boot right now, connect with WireGuard and switch back to AmneziaWG after rebooting into a normal entry. Tirdad and the Realtek and Broadcom Wi-Fi drivers are blocked by exactly the same rule, so if AmneziaWG is missing on a given boot, expect those to be missing too.

Update first: the dashboard's one-click identity controls now change the interface you are connected through as well. Older 10.x builds ran a plain mac-change-all from the dashboard, which skips that interface. On a laptop with only Wi-Fi, or only one cable, it is the only interface, so nothing changed, the Identity panel showed a red NO_CHANGE notice and stopped before changing the hostname and timezone. Get the fix with:

The dashboard's Identity panel, its wizard and its Randomize buttons now run:

That also changes the interface in use while VPN routing and Tor are off: the link drops for a few seconds and comes back. If a VPN or Tor is on, Kodachi keeps that interface, says why, and the output offers Run again with --force, which disconnects the protection first. The panel also reports how many of the three changes (MAC, hostname, timezone) went through. The one order that matters: change your identity before you connect the VPN or Tor. On a Live ISO an update lasts only until you reboot. Your boot-time randomization through NetworkManager is separate and still applies (MAC randomization at boot).

Choices that still skip the active interface. Some controls keep the old behavior on purpose: the Rofi Identity menu's plain Randomize MAC, Circle's Randomize (skip active) and AutoShield's Except active. On a machine with one network interface they change nothing. In the Rofi menu use Randomize MAC (include active), and in Circle use Randomize All.

Why the plain command skips that interface. mac-change-all and mac-change-specific without a flag deliberately leave out the interface that carries your default route, the link your connection and any VPN tunnel or Tor redirect on top of it are using. Changing a MAC takes that link down and up, so a live VPN would drop and the torrify rules would keep pointing at an interface whose identity just changed, leaving a machine that looks connected and is not. When that is the only interface, the command reports:

Forcing it while a VPN or Tor is on. For every interface:

For one interface:

Or the flagless form, which forces by definition:

None of them simply bypasses the guard: each first disconnects the VPN through sudo routing-switch disconnect, undoes system torrification through sudo tor-switch detorrify-system-nftables or detorrify-system-iptables for whichever backend is active, verifies both are clear, and only then changes the MACs; mac-force-change additionally takes every interface down before changing it, which is the form to use when a normal change fails on a driver restriction. They restore nothing afterwards, so reconnect the VPN or torrify again once you are done, and if the check cannot establish the VPN or Tor state the command refuses rather than guesses. The same forcing forms are exposed as separate, confirmation-gated entries in the dashboard Identity actions, Randomize MAC (drops protection) and Force Change (drops protection), and in the Rofi Identity menu as Randomize MAC (drops protection) and MAC Force Change. --anyway is an older spelling of --force with identical behavior. If you lose connectivity afterwards, open the Network Recovery Wizard in the dashboard or run:

Use Libera.Chat's onion service instead of irc.libera.chat, and tell the Tor instance your IRC client uses where that service is. A connection to irc.libera.chat that leaves Tor through an exit relay can be closed right after you log in. The onion service is the route Libera.Chat supports for Tor users, and it needs an account you registered without Tor plus public-key SASL: EXTERNAL with a client certificate, or ECDSA-NIST256P-CHALLENGE. PLAIN is refused there.

First find the SOCKS port of the Tor instance your client will use. The default instance listens on 9050, and the extra instances of the pool start at 10000:

Add the mapping to that instance's custom configuration. For the default instance:

For another instance the file is /etc/tor/kodachi_tor_data/<instance>/torrc.custom. Keep the leading \n: the file often ends without a newline, and a line glued onto the previous one stops Tor from starting. Then restart that instance so Tor reads the mapping:

In the IRC client set a SOCKS5 proxy on 127.0.0.1 with that port, the server palladium.libera.chat, port 6697 with TLS on, and SASL EXTERNAL. The server certificate is issued for palladium.libera.chat, so it verifies without a warning.

If the client still reports host not found, first check that the line went into the instance whose port the client uses. If it did, the client is looking the name up itself instead of passing it to the proxy, and only Tor knows that name. Map a private address to the onion instead, restart the instance again and use that address as the server:

The client then warns that the certificate does not match 10.40.40.40. That is expected: accept it for this server only, because the onion address itself proves which server you reached. Kodachi's Tor refuses a bare IP address that has no mapping, so this route only works with the MapAddress line in place.

You do not need a LongLivedPorts line for IRC on 6667 or 6697: Tor already keeps those streams on stable relays. Add one only for a port outside Tor's default list (21, 22, 706, 1863, 5050, 5190, 5222, 5223, 6523, 6667, 6697, 8300).

The mapping lives in that instance's file only, so a newly created instance does not have it. tor-switch rewrites the file each time it starts the instance; it keeps MapAddress lines and drops comments. The same MapAddress approach works for any other onion service you reach from a program that is not a browser.

There are two good routes. For streaming, connect to a trusted VPN on a server in the US and turn Torrify off for that session. If you would rather keep Tor, leave your VPN connected and pin every Tor instance to US exit relays. Neither is guaranteed: services such as Tubi block known Tor exits and many VPN address ranges, so a site can still refuse you on either route.

Route 1, a US VPN server (the one to try first for streaming). Connect to a trusted VPN provider on a US exit server, either from the External VPN Providers tab (using a provider account inside Kodachi) or with the provider's own app (the DNS step a third-party VPN app needs). Then turn Torrify off, otherwise the site still sees your Tor exit IP instead of the VPN server. In the dashboard that is Essentials → Tor Essentials → Torrification → Detorrify nftables (or Detorrify iptables), and from a terminal:

On a system torrified with iptables, run this one instead:

This is usually the fastest and most reliable route for video. Torrify again when you are done watching.

Route 2, keep the VPN and Tor, and exit in the US. If you are torrified over WireGuard, OpenVPN or another tunnel, both layers can stay on while Tor is told to leave only through US exit relays:

Use the -all form. Torrified traffic is spread across several Tor instances, and a plain set-exit-node us changes only the default instance, so some connections would still leave from other countries. In the dashboard, pick United States under Essentials → Tor Essentials → Exit Nodes and press Set exit country on all. Check the exit IP of every instance with:

Return to normal exit selection afterwards with:

Open the site in a regular browser such as LibreWolf: Tor Browser builds its own circuits and does not follow this setting (why Tor Browser shows a different country). Expect it to be slower than a plain VPN because of Tor's extra hops. Pointing just one browser at a trusted US proxy works on the same principle, since the site then sees the proxy's address.

Choosing the country. For everyday use, avoid a VPN server in your own country: routing through another jurisdiction is part of the protection a VPN gives you. Use the US server for the session that needs it, then switch back. It is always a balance between privacy, anonymity and access.

Port 9050 belongs to Kodachi's main Tor daemon, and it listens only while that daemon is running. Start it, then check the port. Starting Tor needs you to be signed in first; if it says you need to log in, sign in with sudo online-auth authenticate (getting signed in):

The main daemon uses SOCKS port 9050, control port 9051 and transparent port 9040. The Tor instances the dashboard starts for load balancing are a separate pool and never use 9050: their SOCKS ports start at 10000 and their control ports at 12000, and each new instance takes the next number. Kodachi keeps counting from the last number it handed out, so after instances are deleted and created again the ports can be higher. List the real ports, and the live exit IP of each instance:

In the dashboard the same pool is the table on Lite Classic → Essentials → Tor Essentials, which has a SOCKS and a Control column for every instance. So if you started Tor from there, point your application at the port in the SOCKS column, not at 9050.

The size of the pool follows your RAM: round(√RAM in GB × 1.7), never fewer than 3 and never more than 20 instances (8 GB gives 5, 16 GB gives 7, 32 GB gives 10). See the figure for your machine with:

If an application should use the whole pool through one fixed port, put HAProxy in front of it and point the application at 127.0.0.1:9055:

Sharing your connection with other devices on your network is a third, separate service, the microsocks SOCKS5 server on ports 30050 to 30054 (sharing your connection). How the pool spreads traffic is in Tor load balancing.

Because Tor is already handling your DNS. While the system is torrified, the firewall sends every port-53 query to Tor's own DNS port, so a DNSCrypt resolver started at that moment would receive no queries at all while the dashboard showed DNSCrypt as on. Kodachi refuses instead, changes nothing, and says so with a message that starts DNSCrypt was not started: Tor owns system DNS right now. This is expected behavior, and your DNS is still protected: it goes through Tor.

To use DNSCrypt instead, detorrify first, with Detorrify in the dashboard or from a terminal:

On a system torrified with iptables, run this one instead:

If DNSCrypt was active before you torrified, detorrifying turns it back on by itself, and the refusal message tells you so. Otherwise, or if Encrypted DNS still shows off afterwards, turn it on again:

Check the result in the dashboard status bar, or from a terminal, before you rely on it:

No. It is a warning, not an error: the check still reads Ready and the VPN connects. It points out that NetworkManager re-adds its own default route each time your Wi-Fi or LAN lease is renewed. The tunnel's route normally wins that comparison (metric 0 against NetworkManager's 100), so your traffic stays in the tunnel; the warning tells you that this comparison is the whole margin.

Pinning the profile is optional hardening, and it is a trade. Use the network name the warning shows:

With that set, the profile provides no default route at all while no tunnel is up, including at boot, so the machine cannot reach a VPN server to reconnect until you connect a tunnel by hand. Undo it with:

Pin only the Wi-Fi or LAN profile you keep beside a tunnel. If a VPN connection really fails, the reason is further down in the connect output (or the dashboard's Output panel), not in this warning. A connection that keeps failing and then works right after you sign in again usually had expired connection details; re-authenticating fetches fresh ones (re-authenticating cleanly).

Read the sentence before Refusing to torrify: it names the instance, the cause and the fix to try. Kodachi refuses to torrify when a Tor instance cannot carry traffic, because routing your whole system through it would cut your connection. The main cases, and what to do:

• The command did not finish within its time limit. Only in this case firewall rules may already be partly applied, so restore a clean state first with both of these, then go through the checks below:
  sudo tor-switch detorrify-system-nftables
  sudo tor-switch detorrify-system-iptables
• A pool-wide restart is still running. Connecting or disconnecting a VPN restarts every Tor instance in the background. Wait the number of seconds the message gives, then torrify again.
• The instance did not finish bootstrapping after a restart, or it is alive but cannot complete a circuit. Tor is running but cannot reach the Tor network, and for the second case the message adds that a restart will not help. Check that the machine is online and not stuck behind a hotel or airport sign-in page, that a VPN or firewall change has not just moved your route, and that the clock is right, because Tor rejects the network's directory when it is not:
  timedatectl
  On a network that blocks Tor, give Tor bridges, for example from a file of obfs4 bridge lines (bridge management):
  sudo tor-switch set-bridges --from-file ~/bridges.txt
• Kodachi cannot reach the instance's control port, the instance rejected its control-port authentication, or it failed to restart. Check the instances first:
  tor-switch list-instances
  Then restart the one the message names (its tag is in the message, kodachi_tor_inst_1 below is an example):
  sudo tor-switch restart-instance kodachi_tor_inst_1
• The whole pool went stale, typically after a suspend and resume or a long idle. Restart all instances:
  sudo tor-switch restart-all-instances

Then check that every instance is running and torrify again:

Outside the time-limit case, the refusal leaves your routing and firewall as they were; on the way, Kodachi may already have asked the instance for a new circuit or restarted it while trying to heal it. The first torrify after a boot can take a minute or two while the instances build their circuits, so give it that time before you retry.

Pi-hole is an optional DNS filter: it blocks ad and tracker domains for the whole machine and lets you see which domains your system and your apps look up. It does not replace the VPN, Tor or DNSCrypt. Kodachi puts it in front of DNSCrypt, which stays its encrypted upstream resolver, so you get the filtering and encrypted DNS at the same time, with or without a VPN. Turn it on with:

Kodachi then runs Pi-hole on port 5353, redirects the system's port-53 DNS queries to it and points it at DNSCrypt. Check it with:

Turn it off again with:

With Tor. While the system is torrified, every port-53 query goes to Tor instead (why Tor owns DNS then), so Pi-hole's filtering does not apply to that traffic. After you detorrify, Pi-hole takes over again by itself: since the 2026-10-22 update, stopping Tor DNS or detorrifying no longer removes a working Pi-hole's redirect. dns-switch pihole confirms it.

Two more limits. It cannot be turned on while a third-party VPN app owns DNS (External VPN DNS on, see third-party VPN apps), because both need to own system DNS. And if the Pi-hole package is missing, the command says so; install it with (single packages):

Sharing your protected connection is built in, through the microsocks SOCKS5 server. Hosting a website or running a Wi-Fi hotspot is ordinary Debian server work rather than a Kodachi feature. For a machine that does this job, the Terminal Server edition fits best: it is Debian 13 based, has no desktop, and is built for headless gateway and proxy use (choosing an edition).

Share the tunnel with other devices. Connect a routing protocol first, then start microsocks. Microsocks lets the other devices ride the Kodachi machine's active tunnel:

On the other device, set the Kodachi machine's LAN address as the SOCKS5 proxy, with that username, password and the port from the status output (30050 to 30054). Only applications set to use the proxy go through it, and it belongs on networks you trust (sharing your connection, locking the proxy down). Stop it with:

A website. Install Apache, and PHP if the site needs it, the same way as on any Debian server. Kodachi's VPN and Tor routing protect connections the machine makes; it does not route incoming visitors for you, and a site reached through your router's port forwarding shows visitors your real public address. For a public site a separate server is usually the better place. Running a site for a business also needs a license (commercial use).

A Wi-Fi hotspot. NetworkManager can turn a Wi-Fi adapter into an access point the standard Debian way. Kodachi's kill switch, DNS protection and torrify are built and tested for the machine's own traffic, not for traffic forwarded from hotspot clients, so do not count on them for those devices. To give other devices Kodachi's protection, use the SOCKS5 route above.

Open kodachi.cloud with your VPN or Tor connected. The left sidebar on every page shows your exit IPv4 and IPv6 address, its location, whether you come through Tor or a proxy and the network type, plus a WebRTC chip, a Time zone chip, a Hardening chip and a Blocklists check. For the full picture, open kodachi.cloud/tools/ip.html (the IP tab and the Fingerprint tab) and run Kodachi's own leak test on kodachi.cloud/tools/dns.html. If a page looks out of date, press Ctrl+Shift+R to reload it.

Open kodachi.cloud/tools/dns.html, scroll to Kodachi's own leak test and press Run the test. Your browser looks up six random names under leak.kodachi.cloud through the DNS resolvers it really uses; those resolvers ask kodachi.cloud's own nameserver for them, and the card lists every resolver that asked: its address, its network, whether it is in the same network as your address, and any subnet it passed on. It works over IPv4 and IPv6. With a VPN or Tor on you should see your VPN's or Tor's resolvers, or public resolvers you chose yourself. A resolver that belongs to your own internet provider means your DNS lookups leak past the tunnel.

On Kodachi, dns-leak test runs this same test by default: the lookups go to kodachi.cloud's nameserver and no third party sees them, and the result always names the test it used. dns-leak test --provider bash.ws chooses the third-party bash.ws test instead. There is no automatic fallback: if kodachi.cloud cannot confirm the test, the result says so and names dns-leak test --provider bash.ws as the next step.

Some resolvers add a subnet to the queries they send on (EDNS Client Subnet), so the answering nameserver can pick a server near you. The test shows each subnet a resolver passed on and whether it holds your address. Your address's means the subnet holds the address kodachi.cloud already sees for you (your VPN or Tor exit when one is on), so the nameservers it asks learn nothing more about where you are. Not your address's means the subnet belongs to another network: it can be your real location when your lookups leave outside the tunnel, or the network of a resolver that forwards lookups for you, so with a VPN or Tor on it is worth a closer look. none means no subnet was passed on.

WebRTC lets a web page ask your browser for its network addresses, which can reveal your real IP even through a VPN. The WebRTC chip in the left sidebar shows what your browser gives away: local addresses, the public address a STUN server sees, and IPv6. kodachi.cloud asks its own STUN server, so no third party learns your address during the check. If the chip shows an address that is not your VPN or Tor exit, turn WebRTC off in your browser (in Firefox-based browsers, set media.peerconnection.enabled to false in about:config).

With the Monitor switch in the left sidebar on (it is on by default), kodachi.cloud checks your exit address again every 30 seconds while one of its pages is open and in view. When the address changes, for example when Tor builds a new circuit or your VPN reconnects, an alert titled IPv4 Address Changed or IPv6 Address Changed shows the new address with its country, city and flag, and a Whois button that shows who holds it. Turn the switch off to stop the checks.

Let the VPN app on the host allow Kodachi's DNS servers. In the Mullvad app open Settings, then VPN settings, turn on Use custom DNS server and add 1.1.1.1, 9.9.9.9 and 94.140.14.14. Keep the virtual machine's network on NAT, then refresh the network status in the dashboard or restart the virtual machine.

Why it happens: Kodachi resolves names itself, with encrypted DNS and 1.1.1.1, 9.9.9.9 and 94.140.14.14 as its fallback servers, instead of using the DNS forwarder built into VirtualBox or VMware. Mullvad's leak protection on the host drops DNS sent to any server it was not told about. Ping still works, DNS fails, and every HTTPS check fails behind it, while other guests that use the hypervisor's DNS keep working.

Your DNS still travels inside the host's Mullvad tunnel, so nothing leaks. The trade-off is that Mullvad's own DNS content blockers are off while custom DNS is on. Other host VPN apps with a DNS leak guard have a similar custom DNS setting. More VM advice: testing Kodachi in a VM.

For Kodachi's own servers, Kodachi builds each VPN profile when you connect and deletes it when you disconnect, so empty /etc/openvpn and /etc/wireguard folders are normal and nothing needs to be downloaded. On connect, routing-switch creates the session configuration from your signed-in connection card in Kodachi's own runtime folder; on disconnect it removes it. A search of the disk before or after a session finds nothing for them. Profiles you import yourself are different: they are saved, so you can pick them again.

When a connection fails, the reason is in the connect output, not in missing files. Connect from a terminal and read the lines after the Network prerequisites check (a NetworkManager line there is a warning, not the failure):

Check that your session is valid:

A WireGuard handshake timeout usually means the network blocks WireGuard's UDP traffic: sign in again for a fresh card, then try AmneziaWG (what AmneziaWG is) or OpenVPN. To use a profile of your own, import it (pasting your own config) or pass the file directly:

Tor carries only TCP connections, and calls use UDP. With the whole system routed through Tor (Torrify System), Kodachi drops every UDP packet to the internet except DNS so that nothing can leave outside Tor, so voice and video in Discord and similar apps fail while their text chat keeps working. For calls, connect a VPN instead of routing the whole system through Tor (VPN protocols); Tor Browser and other Tor-only apps are unaffected.

This is the leak protection doing its job, not a fault in the app.

It is a 0-100 score computed by sudo health-control security-score that aggregates 7 weighted categories: System Security (30 pts), Privacy & Anonymity (25 pts), Network Security (20 pts), Authentication (10 pts), Device Security (5 pts), Advanced Privacy (5 pts), and Data Protection (5 pts). The result maps to five tiers: Excellent (90+), Good (75-89), Fair (60-74), Partial (40-59), and Critical (under 40).

Each category contains individual weighted checks. The denominator is adaptive: checks that physically cannot apply on your system are excluded rather than counted as failures - for example a live ISO drops disk encryption, swap encryption, auto-updates, encrypted containers, and backup encryption; a BIOS-only machine drops Secure Boot; a headless system drops Bluetooth/webcam. That is why the total may read e.g. 57/82 instead of 57/100. The score is a percentage of applicable points, so both a live ISO and an installed system can still reach 100%.

Privacy & Anonymity is worth 25 points: Tor + system torrification (8 pts), DNS privacy via DNSCrypt/DoH/DoT/DNSSEC (7 pts), an active VPN or proxy (6 pts), privacy-focused browser configuration (2.5 pts), and MAC randomization (1.5 pts). VPN/proxy and Tor are scored independently, so running both layers them additively rather than one replacing the other.

System Security is the largest category at 30 points: LUKS full-disk encryption (8 pts), an active firewall (8 pts), encrypted swap (4 pts), auto security updates (4 pts), UEFI Secure Boot (3 pts), kernel hardening (2 pts), and AppArmor/SELinux (1 pt). On a live ISO the encryption, swap-encryption, and auto-update checks drop out of the maximum because they cannot apply.

Enable more applicable protections. The biggest practical levers are: connect a VPN/WireGuard, enable DNSCrypt, torrify the system through Tor, and (on installed systems) install with LUKS full-disk encryption and keep auto-updates on. Apply hardening with:

Use security-remediate to fix flagged weaknesses and security-verify to confirm the state. The score only rises when you enable protections that actually apply to your hardware and session.

Kodachi has 7 independently enableable hardening modules plus preset profiles. Standard is balanced, network-safe hardening (kernel, network, memory) suitable for daily use. Paranoid applies all 7 modules at maximum - network isolation, sandboxed processes, aggressive filesystem restrictions - for high-threat scenarios, but it may break browsers, internet access, and some applications. Break-Monitoring adds active breach detection with file integrity tripwires and anomaly alerting. Apply hardening with:

Only push toward 90+ if you genuinely need it, since aggressive hardening sacrifices convenience.

Not necessarily. A score of 50-65 with VPN + DNSCrypt + firewall active is already far more secure than the vast majority of operating systems. Pushing to 90+ stacks aggressive features (Secure Boot + LUKS + full hardening + Tor) that can cause service breakage, hardware-detection issues, and longer boot times. Only target 90+ when you are protecting something truly critical and accept that convenience will suffer.

Because the denominator is adaptive. On a live ISO, disk encryption, swap encryption, auto-updates, encrypted containers, and backup encryption are marked N/A and drop out of the maximum - a fully hardened live session still reaches 100%, and an installed system hardened to the same level reaches the same ceiling, so the two can score identically. On an installed system those checks become active; an installed system without LUKS scores lower than the same-effort live session because the disk-encryption check is now applicable and failing. Kodachi does not penalize USB-boot users and does not reward installation by itself - only enabling more applicable protections raises the score.

No. Checks that cannot physically apply to your system (disk encryption on a live ISO, Secure Boot on a BIOS-only machine, Bluetooth/webcam on a headless box, WiFi on a wired-only host) are excluded from the maximum, not scored as zero. They drop out of the denominator entirely, so an inapplicable check can never count as a failure against you.

Yes, two independent paths exist. (1) Boot-time LUKS nuke: when you install with full-disk encryption using the Debian text installer entry "Install Kodachi (Text + Full Disk Encryption, Boot-Nuke Compatible)", a cryptsetup-nuke-password is configured - entering that special passphrase at the boot LUKS prompt instantly destroys the encryption headers, rendering the drive unreadable. (2) Dashboard/CLI duress path: health-control has three panic levels plus the separate Destroy operation: Soft (kill network, lock screen, wipe clipboard), Medium (+kill processes, clear memory caches, unmount volumes), Hard (+forced power-off, then a RAM wipe until the power goes, no screen lock), and Destroy (every LUKS header and Kodachi's own header backups wiped, removable drives only if you opted in, then Panic Hard; no password opens a wiped device again, and only a header backup kept outside Kodachi's own backup folder could restore one). The difference: the boot nuke triggers from the encryption passphrase prompt before login and needs the boot-nuke-compatible install layout; the panic path runs from a logged-in session and escalates through reversible-to-irreversible levels. See also the full step-by-step destruction paths and which panic tiers are recoverable.

The boot-time nuke works at the initramfs LUKS passphrase prompt - entering the special nuke password destroys the disk encryption headers before anyone logs in, which is ideal for a coerced unlock at a border or seizure. It requires installing via the Debian text installer "Boot-Nuke Compatible" encrypted entry so /boot stays outside LUKS (the Calamares GUI encrypted install can place the first LUKS prompt in GRUB, which blocks duress-at-boot nuke). The dashboard/CLI panic path (health-control panic-soft/medium/hard plus the separate Destroy operation) runs from a live session and can stop at reversible levels (network kill, screen lock) or escalate to RAM wipe, forced shutdown and LUKS header destruction. See also the full step-by-step destruction paths.

Kodachi provides three independent destruction paths, each suited to a different scenario.

1. Destroy Kodachi sidebar icon. A red Destroy Kodachi icon (skull) is the last icon at the bottom of the left rail, present on all five dashboards. It can be shown or hidden from Settings › Security. Clicking it opens an in-window confirmation dialog (style is configurable in Settings: type DESTROY (default), a Yes/No prompt, or immediate with no confirmation), then runs a two-stage sequence: first it permanently wipes every LUKS device on internal and boot media, unlocked or locked, together with its automated header backups (removable USB drives too only if you turned that on in Settings; no password opens a wiped device again, and only a header backup kept outside Kodachi's own backup folder could restore one), then it runs Panic Hard: network cut, clipboard and memory caches cleared, removable devices unmounted, forced power-off, then a RAM wipe until the power goes. While it runs, the screen shows only update wording (“Updating Dashboard Components”), so an onlooker sees a routine update. It wipes no individual files and leaves the boot chain alone: those belong to the Dashboard Nuke below. It is irreversible once triggered.

2. Emergency global keyboard shortcuts (session helper). The kodachi-session-helper daemon registers session-wide hotkeys that work anywhere in the X11/XFCE session, even when the dashboard window is closed. Hold the modifier keys (at least three modifier keys for the LUKS header wipe and the combined nuke, two for the dashboard nuke, one for delayed lockdown) plus a trigger key for the hold time: the helper's built-in times are 1.5 s for the dashboard nuke and delayed lockdown, 2 s for the LUKS wipe and 2.5 s for the combined nuke, saving in Settings applies one time to all four (2 s is the recommended choice), and the helper refuses anything under 500 ms; auto-repeat is rejected. By default a press counts only when raw /dev/input events corroborate the X11 key grab, so synthetic input (XTEST) is refused; on a VM whose virtual keyboard never reaches /dev/input that check can be switched off, and then synthesized keystrokes can fire a shortcut. Configure them in Settings > Security > Emergency Protocol. The shortcuts fire the Dashboard Nuke (health-control's 14-phase wipe, which also destroys the boot chain), the LUKS header wipe of the device you chose, both together (network kill, then the LUKS wipe, then that nuke), or a delayed lockdown (a cancellable countdown to one of those); all four are off until you set them, and none of them fires a panic level. X11 session required, Wayland is detected and fails closed.

3. LUKS Nuke (Emergency page + boot-time). On the dashboard's Emergency page (Sidebar › Essentials › Emergency), the LUKS Nuke control lets you immediately destroy the header of a selected encrypted device ("Execute Nuke"), so no password opens it; it leaves header backups alone, so a backup you made can still restore the device. Separately, if you installed using the Debian text installer entry "Install Kodachi (Text + Full Disk Encryption, Boot-Nuke Compatible)", you can configure a special boot-time nuke password via Dashboard > Emergency > LUKS Nuke: entering that password at the initramfs LUKS prompt at boot triggers instant header destruction before login, ideal for coerced-unlock scenarios at a border or seizure. A fourth path also exists: the duress password entered at the dashboard login screen shows a convincing fake "System Update" screen while the Dashboard Nuke runs silently behind it (health-control's 14-phase wipe, or the dashboard's own nine-phase sequence if health-control is missing or does not finish successfully).

All destruction actions are irreversible. If you need a recoverable emergency response, use Panic Soft (kills network, wipes clipboard, locks screen) or Panic Medium from health-control instead. See also boot-time LUKS nuke vs dashboard panic and which panic tiers are recoverable.

Kodachi can inspect selected signals. Locally, ip-fetch check-tor reports whether the tested request exits via Tor, while dns-leak test and routing-switch dns-info report visible DNS routing. Online tools inspect IP, DNS, Tor, and browser-fingerprint signals. These checks can reveal specific route, resolver, and browser-metadata problems, but they cannot rule out application metadata, account correlation, endpoint compromise, or timing and traffic correlation. They therefore do not prove anonymity as a whole.

It can be, when you enable it. health-control includes a RAM wipe system that runs from a systemd shutdown hook. Turn it on from the Dashboard, or with sudo health-control wipe-ram-install and then sudo health-control ram-wipe-enable. At shutdown it overwrites the free memory it can reach (with kodachi-wiper, sdmem or both) within its time budget, which limits what a cold-boot attack can recover from frozen RAM. It is not forced by default; you turn it on, and Panic Hard, and Destroy, which runs it, also start a fast RAM wipe that runs only until the power goes. The forced power-off skips the shutdown steps, so the installed shutdown wipe does not run.

Yes. health-control offers granular secure-deletion: wipe-file (custom pass count), wipe-directory, wipe-batch, wipe-logs (system/all), wipe-browser-data (per browser or all), wipe-free-space, wipe-pattern (e.g. *.tmp), plus scheduled wiping (wipe-schedule temp --frequency daily) and wipe-verify to confirm a file was destroyed. These let you scrub targeted data without destroying the whole disk. Pass count is configurable (for example wipe-file --passes 7), and all wipe operations require sudo and are irreversible.

Yes. integrity-check verifies file signatures and hashes so you can confirm binaries have not been tampered with, and health-control provides a security score across system hardening, privacy configuration, network protection and authentication status. health-control also includes hardware/USB device protection and net-check diagnostics, so you can continuously confirm the system is in a known-good state.

Partly. Once you turn it on, the RAM wipe runs from a systemd shutdown hook and overwrites the free memory it can reach within its time budget, so an adversary who freezes RAM chips afterwards has less to extract. It needs an orderly shutdown: a machine seized while running is not covered by it. Cold boot defense adds an overwrite of free memory before suspend or hibernate and on power loss. You can choose the wipe engine, check the setup with a dry run (sudo health-control wipe-ram-test), and the installer can enable the init_on_free=1 kernel parameter for additional memory hygiene.

Yes. The Lite Dashboard diagnostics menu includes Conky Mask Enable / Disable / Status, which mask sensitive fields such as IP, MAC and country data in the Conky panels so you can screenshot safely, then restore the real values when you unmask. You can also fully hide the Conky overlay from Settings > Dashboard > Conky Control.

Not out of the box. Tirdad is an add-on (DKMS) kernel module signed with a certificate generated during the Kodachi build, which no machine trusts. With Secure Boot on, the kernel enforces module signatures on every boot entry, so it refuses to load Tirdad. The quick answer is to switch Secure Boot off in the firmware: then Kodachi Live, Persistent, Encrypted Persistence, CPU Hardened and DMA Protection all run Tirdad.

Both at once, on an installed UEFI system. Sign Tirdad with a key of your own and enrol that key. Create the key and rebuild Tirdad with it:

Enrol the key; mokutil asks you to choose a one-time password:

Reboot. On the blue MOK Manager screen press a key, choose Enroll MOK, Continue, Yes, type the password and reboot (that screen times out quickly). Switch Secure Boot on in the firmware, boot Kodachi, and check the key:

Load Tirdad and confirm it is running:

Kodachi's own Tirdad loader still steps aside while signatures are enforced, so make it load at every boot yourself:

Kernel updates rebuild Tirdad and sign it with the same key, and Kodachi's Tirdad status may keep showing N/A, so check with lsmod. dkms generate_mok creates a new pair only when /var/lib/dkms/mok.key or mok.pub is missing, and images built after 4 September 2026 ship without mok.key, so on those the key is yours alone. On an image built on or before 4 September 2026, which may have shipped mok.key, move mok.key and mok.pub out of /var/lib/dkms before you start (why). Keep mok.key private: the machine trusts anything signed with it. If mokutil answers Key was rejected by service, the key is not enrolled yet.

This is correct, intentional behavior, not a bug. The kernel blocks loading any module whose signing key it does not trust when lockdown is active or module.sig_enforce=1 is set, and Tirdad is signed with a build-time certificate that is enrolled nowhere. In the Kodachi boot menu, Kernel Lockdown (confidentiality) and Full Hardening set module.sig_enforce=1, and Maximum Privacy and Full Hardening set lockdown=integrity - any of these blocks Tirdad. Forensics Mode blocked it too from 2026-09-04, when it gained lockdown=integrity as part of making the tiers a strict superset chain. Current ISOs report the truth and the score marks Tirdad N/A instead of penalizing you; reboot into Live, Persistent, Encrypted Persistence, CPU Hardened, or DMA Protection to actually run it.

There are two prerequisites. First, you need an actual LUKS-encrypted partition: the nuke password destroys LUKS keys, so you must have booted Encrypted Persistence or installed with full-disk encryption - a plain live or unencrypted-persistent session has no LUKS device to attach a nuke key to. It also needs the health-control binary and the cryptsetup-nuke-password package (pre-installed in the ISO); if health-control luks-detect finds no LUKS device, there is nothing to configure. Second, the LUKS unlock prompt must stay in initramfs: if you used the Calamares GUI encrypted install the first prompt may land in GRUB instead, which blocks duress-at-boot nuke, so the dashboard fail-closes and refuses to configure it - reinstall from the GRUB Debian-installer entry 'Install Kodachi (Text + Full Disk Encryption, Boot-Nuke Compatible)', which keeps /boot outside LUKS. The manual 'Execute Nuke' for the selected device still works as an emergency action even when boot-time nuke is blocked.

The raw cryptsetup luksAddNuke /dev/sdX command does not create any LUKS header backup - that is a known limitation of the manual method. Use this instead, which adds an automatic GPG-encrypted timestamped header backup, LUKS validation, package auto-install, and audit logging:

That is the intended fail-closed behavior, not a malfunction. Entering the nuke password instead of the normal LUKS password instantly overwrites the LUKS header and wipes every key slot, so the boot fails (expected) and no password opens the data again. The only recovery path is the GPG-encrypted LUKS header backup automatically created before nuke configuration (saved under the hooks backups directory), intended for authorized recovery only. It helps only if you copied it off the encrypted disk beforehand: on a full-disk-encrypted install that directory sits on the volume the nuke has just destroyed.

Yes, you can layer them, but order is critical: connect the VPN first, then torrify the system. If you torrify first and then connect the VPN, the VPN rewrites the routing table and breaks the Tor circuits. In AutoShield, let it connect WireGuard (or another protocol) first, then run 'Torrify System + DNS'. See also Can I layer Tor on top of a VPN for double protection?

The kodachi-session-helper daemon that provides them requires an X11/XFCE session; Wayland is detected (XDG_SESSION_TYPE/WAYLAND_DISPLAY) and the helper fails closed, so the shortcuts do nothing under Wayland. Use an X11/XFCE session and configure them in Settings > Security > Emergency Protocol. They also require holding the modifier keys (at least three modifier keys for the LUKS header wipe and the combined nuke, two for the dashboard nuke, one for delayed lockdown) plus a trigger key for the hold time: the helper's built-in times are 1.5 s for the dashboard nuke and delayed lockdown, 2 s for the LUKS wipe and 2.5 s for the combined nuke, saving in Settings applies one time to all four (2 s is the recommended choice), and the helper refuses anything under 500 ms: a quick tap or auto-repeat is rejected by design.

Emergency shortcuts use hold-to-trigger: you must physically hold the modifier keys (at least three modifier keys for the LUKS header wipe and the combined nuke, two for the dashboard nuke, one for delayed lockdown) plus the trigger key for the hold time: the helper's built-in times are 1.5 s for the dashboard nuke and delayed lockdown, 2 s for the LUKS wipe and 2.5 s for the combined nuke, saving in Settings applies one time to all four (2 s is the recommended choice), and the helper refuses anything under 500 ms, and auto-repeat is rejected, to prevent accidental activation. By default a press counts only when raw /dev/input events corroborate the X11 key grab, so synthetic input (XTEST) is refused; on a VM whose virtual keyboard never reaches /dev/input that check can be switched off, and then synthesized keystrokes can fire a shortcut. Hold the full combination physically and long enough.

Panic Soft loses no data: it cuts the network (the IPv4 firewall set to drop everything, NetworkManager, Tor and OpenVPN stopped, every interface except loopback down), clears the clipboard and locks the screen. Restarting the network does not undo it. Before the cut, Panic Soft and Panic Medium save a recovery journal (your firewall rules, which network services were running, which interfaces were up), and the panic recovery puts exactly that back:

It is auth-exempt, so it works with the network down; the Recover button on the dashboard's Emergency page runs it. Panic Medium adds terminating non-essential processes, clearing memory caches and unmounting devices: panic-recover brings the network back, ended processes and unmounted devices do not come back. Panic Hard is IRREVERSIBLE: it ends the same non-essential processes as Medium, clears memory caches, unmounts devices, forces the power off, then starts a fast RAM wipe that runs only until the power goes (it does not lock the screen), and it saves no recovery journal.

Run the panic recovery (a triggered kill switch runs Panic Medium, so this covers it too):

It restores the firewall rules, network services and interfaces that Panic Soft or Medium recorded before the cut, and it is auth-exempt so it works with the network down; on the dashboard it is the Recover button on the Emergency page. Neither of the usual fixes undoes a panic: restarting the network brings NetworkManager back but the panic's firewall still drops everything, and unblock-internet only reverses its own Block Internet, so after a panic it finds nothing of its own to undo and changes nothing. If the network is still dead afterwards, or it was cut some other way, the broader recovery walks a 10-method sequence (clean stale NAT redirects, clear the firewall, flush the route cache, restart NetworkManager through nmcli, restart NetworkManager directly, restart the active interface, renew its DHCP lease, restart all interfaces, renew their DHCP leases, and fix the DNS resolver config), falling through each until connectivity returns:

There is also a lighter 'fast-recover-internet' that tries a quick fix first. From the GUI use Essentials > Actions > Network Recovery > Fix Internet Wizard.

Yes, it does. Kodachi Kernel Lockdown (confidentiality) carries ipv6.disable=1 exactly like every other entry in the menu, on top of its own module.sig_enforce=1 and lockdown=confidentiality. (An earlier version of this answer said it did not, and recommended it as the way to keep a runtime-toggleable IPv6 stack. That was wrong: all 23 live entries disable IPv6 at the kernel, so no menu entry gives you both signature enforcement and a runtime-toggleable IPv6 stack.) What does differ between Kernel Lockdown (confidentiality) and the other top-tier entries is the enforcement itself: Kernel Lockdown (confidentiality) sets lockdown=confidentiality, the strictest mode, which additionally blocks kernel memory reads, kexec, hibernation and eBPF kernel-memory access, while Maximum Privacy and Full Hardening use lockdown=integrity. If you need IPv6 on a live session you have to edit the entry at the boot menu with e and remove ipv6.disable=1 before booting.

Yes. online-info-switch freshness generates a proof-of-freshness report that combines the current UTC and local time, your live IP and country, fresh security-news headlines, the current Bitcoin block height, and live cryptocurrency prices. Because the Bitcoin block height and news headlines change constantly and cannot be predicted in advance, the bundle demonstrates the snapshot was produced at that moment rather than replayed from an old recording. You can emit it as --json or --json-pretty for automation, and it does not require sudo.

Yes. integrity-check maintains baseline checksums for critical system files and binaries using BLAKE3 hashing (with SHA-256 as a fallback) and also performs cryptographic signature verification, so both unauthorized file modification and unsigned/forged binaries are detected. It supports scheduled and on-demand scans, configuration-file monitoring, custom file lists and exclusion patterns, and an offline mode. This is what backs Kodachi's binary authentication and tamper detection.

Yes. permission-guard is built specifically to monitor file ownership and permissions and automatically correct insecure ones, including root-owned files that end up in user directories after privileged operations. It does real-time monitoring across configurable watch directories with pattern-based exclusions, can run as a background daemon, and outputs JSON or text. This is also why you stop permission-guard before a binary update, so it does not revert ownership mid-update.

Yes. workflow-manager uses a hybrid conditional system that combines success/fail states with regex and substring pattern matching and JSON-path evaluation (dot fields plus array indexes), so a step can branch on a specific value inside a previous command's JSON response. It also supports prerequisites validation, system-state probes, retry logic, concurrent execution within a workflow, interactive pause checkpoints, dry-run mode, and JSONL telemetry logging. It ships with 122 ready-to-use built-in profiles, and you can add your own.

No, not on the licence path. online-auth talks to the license server only over HTTPS (TLS 1.2 or newer), refuses a plain-HTTP or non-kodachi.cloud address, and checks the server certificate against your system's CA bundle. It does not pin a specific certificate, so it trusts the same certificate authorities your system trusts; a rogue or compromised authority in that bundle is outside what it can detect.

Your hardware information stays private. To recognize a machine, Kodachi builds a privacy-preserving fingerprint by running stable system characteristics through SHA-256, a one-way hash. Only the resulting hash is ever used, and the source device details stay on the computer in this path, while the stable hash can still link authentication attempts from the same machine.

A one-way hash cannot be turned back into the original values, so this fingerprint lets Kodachi recognize a returning machine and keep abusers out without sending the source hardware fields. This does not make the device or session anonymous. Authentication also asks for no email and no phone number (see is authentication tracking me), so the service works without ever needing to know who you are.

By design. LibreWolf runs under a strict AppArmor profile so that if the browser is ever exploited or hijacked it cannot read the rest of your home directory - your documents, pictures, dotfiles, keys and other sensitive files stay out of reach. The profile deliberately exposes only ~/Desktop and ~/Downloads (recursively) for opening uploads and saving downloads; everything else under $HOME is sealed off. This is a containment feature, not a bug - keep any file you want to open or save in the browser inside the Desktop or Downloads folder.

Yes. Kodachi Desktop uses the XFCE screensaver (xfce4-screensaver) for the idle lock, and you control both the timeout and whether it locks at all.

To increase the timeout (keep the password lock): open Settings → Screensaver and raise Blank after, then on the Lock Screen tab raise the delay before the password is required. From a terminal as your desktop user the same settings are, in minutes. The idle time before blanking:

The extra delay before the lock engages:

Raise the display blank to match with:

The effective lock time is roughly the idle delay plus the lock delay.

To disable the lock entirely: in Settings → Screensaver untick Enable Screensaver and Lock screen, and in Settings → Power Manager → Display set Blank after to Never. The terminal equivalent is:

Followed by this, to stop X11 blanking in the current session:

Note that disabling the lock leaves the machine unlocked whenever you step away, so raising the timeout is the safer choice for most users.

No, enrol a key of your own instead. The certificate that signs Kodachi's 37 DKMS modules is generated automatically while the image is built. Images built after 4 September 2026 ship only that certificate (/var/lib/dkms/mok.pub) and remove its private key, so it can never sign anything again: the next kernel or module update rebuilds the modules, and a certificate whose key is gone cannot cover them. Images built on or before that date could go further wrong and shipped the private key itself, at /var/lib/dkms/mok.key, so everyone who downloaded the same ISO held it. Enrolling that certificate would tell your machine to trust any kernel module signed by anybody with that image, which is the opposite of what Secure Boot is for: a kernel module runs with full kernel privileges. If /var/lib/dkms/mok.key was already on your system when you installed it from an image built on or before 4 September 2026, or you cannot tell where it came from, never enrol its certificate. A key that DKMS or dkms generate_mok made on your own machine is unique to it.

Do one of these instead. Simplest: reboot into a boot entry that does not enforce module signatures (Kodachi Live, Persistent, Encrypted Persistence, CPU Hardened, or any Advanced entry; Forensics gained lockdown=integrity on 2026-09-04 and no longer qualifies) and keep Secure Boot off, which is the normal live-session answer. Or accept the loss and stay hardened, using WireGuard rather than AmneziaWG and a wireless adapter with an in-tree driver. Or, on an installed system where you control the machine, create your own key pair with:

Point /etc/dkms/framework.conf at it with mok_signing_key and mok_certificate, then rebuild the modules with:

Then import the certificate:

And complete the enrolment in the blue MOK Manager screen on the next reboot. For Tirdad alone there is a shorter route with dkms generate_mok (steps). That key stays yours, so the trust you grant is yours alone. Kodachi's own boot chain does not depend on any of this: GRUB and shim on the ISO are signed by Debian and Microsoft's UEFI CA, so the system boots with Secure Boot on regardless.

Allow that one device by its ID. List your USB devices and note the vendor:product pair after ID, then add it to the whitelist (the ID below is an example):

The device then connects normally. From the dashboard, whitelisting works only for an account in the sudo group (adding an account to it), because the dashboard cannot ask for a password. Whitelisting and turning USB Guard on need you to be signed in; if a command answers Authentication required, sign in first (getting signed in). See the whitelist with:

Take a device off it with:

Switching USB Guard off is an emergency command that works without a sign-in, so you can always do it:

What it blocks. USB Guard is off by default. When you turn it on, from the dashboard's Hardening page, USB tab, or with the command below, Kodachi's policy blocks USB storage and USB network adapters, the classic tools of a BadUSB attack, and allows keyboards, mice and touchpads, hubs, audio devices, webcams, smartcard readers, printers and the laptop's built-in Bluetooth. Every other device is rejected until you whitelist it:

Keyboard and mouse. Keyboards, mice and touchpads are allowed, and binary packs newer than build 63 also keep every keyboard, mouse and hub that is plugged in when USB Guard starts. On binary pack 63 and earlier, turning USB Guard on could block a keyboard, mouse or USB hub that was already connected: whitelist each one as above, or run the emergency off command above from a built-in keyboard or another login, then update. The one exception is deliberate: a gadget that presents itself as a keyboard and a storage device at once is blocked, because that is how a BadUSB stick works.

Built-in Bluetooth. Laptop Bluetooth chips sit on an internal USB bus. The policy that shipped with earlier 10.x builds did not allow them, so on some laptops turning USB Guard on cut Bluetooth. The current policy allows a built-in chip, and turning USB Guard on after updating replaces an unchanged older policy (a policy you edited yourself is never overwritten). A plugged-in Bluetooth dongle, or a built-in chip whose firmware reports its port as removable, still needs the whitelist step above. Every USB Guard command is on the health-control page.

On the IP tab of kodachi.cloud/tools/ip.html, kodachi.cloud reads the first packet of the latest connection it saw from your address and shows what system it looks like, the link type when the packet size reveals it, and the network distance, next to the system your browser claims. Differs from your browser means something between you and the site opened the connection (a proxy, a Tor exit, the network of a virtual machine), or your browser reports a different system on purpose, for example through a privacy setting. With Tor or a VPN a difference is normal. The reading is kept in memory only, until 15 minutes after your address's last connection, and is answered only for your own address.

Every HTTPS connection starts with a TLS handshake that lists the versions, ciphers and extensions your browser supports. Browsers of one make and version send the same versions, ciphers and extensions, so the handshake tells a site which browser you really run, even when the user agent says otherwise. Some browsers shuffle the order of their extensions on every connection, which changes JA3; JA4 sorts them, so it stays the same. The Fingerprint tab of kodachi.cloud/tools/ip.html shows your JA4 and JA3 fingerprints, the highest TLS version, the post-quantum key exchange and Encrypted Client Hello. Matches the Kodachi browser means your handshake is the one the browser shipped with Kodachi sends; Differs means you use another browser or version, which is not a problem by itself but makes you look like a user of that browser. The handshake is read by kodachi.cloud's own listener on port 8443, and nothing is kept.

Time zone compares the time zone your browser reports with the country of your exit IP; a mismatch is a common way websites spot VPN and Tor users (see the timezone question for how Kodachi can match them). Hardening shows whether your browser's fingerprint protection is active and visible, for example a noisy canvas or letterboxing. Blocklists asks public spam and abuse lists, only when you click, whether your exit IP is listed, which explains CAPTCHAs and blocks; a shared VPN or Tor exit is often listed through no fault of yours.

The DNS leak test keeps which resolvers asked for your random test names in memory for 10 minutes and writes nothing to disk. The connection check keeps its reading in memory until 15 minutes after your address's last connection, answers only for your own address and writes nothing to disk. The TLS check and the STUN server keep nothing. The fingerprint timeline on the IP page is kept only in your own browser, with a Forget button. To name your network (the sidebar's Proxy chip, the IP page and the leak test's resolvers), kodachi.cloud asks RIPE NCC about the address and keeps the answer, the network's number and holder, on the server for up to 12 hours. The Blocklists and Whois buttons ask the public lists and registries only when you click them; a Whois answer is kept up to 12 hours and a complete Blocklists answer one hour. The location in the sidebar comes from public geolocation services, which receive your address when kodachi.cloud has no stored answer for it from the last 30 days; kodachi.cloud keeps the address with its location and network for 30 days for its visitor statistics, and after that only a count per country and day.

You can support Kodachi financially through documented channels: direct cryptocurrency donations (Bitcoin, Monero, USDT, BNB, Dogecoin, Litecoin, Ripple, Polkadot and more - cryptocurrency payments can reduce the identifying data shared with conventional payment processors), and third-party donation services NOWPayments (nowpayments.io/donation/linuxkodachi), PayPal (paypal.com/ncp/payment/TJZSGR6452HS4) and Donorbox (donorbox.org/kodachi). Every address and link is listed on the Donate tab in a list signed with the Kodachi OS repository signing key, so you can verify it before you send. You can also purchase a Premium or Custom license (an annual license covering 12 months of all updates, no auto-renewing subscription, privacy-oriented payment, including Monero, supported). Donations help sustain the free personal-use tier and shared VPS infrastructure but do not grant license keys or premium access.

Yes. Beyond donations and licenses, genuinely helpful word-of-mouth support includes sharing your experience on social media (X/Twitter, LinkedIn), creating YouTube tutorials or blog write-ups, and spreading the word in privacy communities so more people discover the project. You can also participate in the Discord community (https://discord.gg/KEFErEx) for real-time support and discussion, report bugs and submit feature requests there, and contribute on GitHub if you have the technical skills. These are real ways to help even if you cannot contribute money.

No. Donations help sustain the free personal-use tier and shared infrastructure but do not grant a license key or paid entitlement. Premium and Custom are separate annual licenses covering 12 months of all updates, with no automatic renewal. Purchasing requires no registration or account: buy a key, including with privacy-preserving options such as Monero, then enter it once through online-auth or About > Premium License. The dashboard stores the resulting short-lived, signed, device-bound entitlement and automatically verifies it on later starts while it remains valid.

No. Personal use does not require a paid license; commercial, professional, or organizational use does. Kodachi OS and its privacy protection core remain free. Free includes Circle and Lite Classic, the Simple and Direct startup screens, every appearance pack, accessibility and performance controls, one Default preference profile, current-session history, and the normal managed pool. Premium adds the Vitals system monitor, the top-level SOC dashboard, the ColonyOps operations workspace, the Advanced startup launcher and the VPN Providers and Mobile Manager pages in Lite Classic, persistent command history and low-density managed nodes. Which features are Premium is set on the Kodachi license server and shown live on the support page; a signed-in Kodachi 10 dashboard picks up a change within about ten minutes.

Community support is available through the extensive documentation, Kodachi Discord at https://discord.gg/KEFErEx, and GitHub at github.com/WMAL. No registration or personal account is required to use Kodachi or purchase a license. Paid reports receive best-effort priority triage, but this is not an SLA. Custom adds direct written support from the developer: email and private Discord messages, 12 cases per organization per license year, no phone calls, video calls or screen-sharing. Every tier keeps the same hardened privacy and protection core; Premium adds the Vitals system monitor, the top-level SOC dashboard, the ColonyOps operations workspace, the Advanced startup launcher and the VPN Providers and Mobile Manager pages in Lite Classic, persistent command history and low-density managed nodes. Live service status is at /apps/status.php and the warrant canary is at /tools/warrant.html.

Kodachi has been independently developed since 2013 and is used by privacy-conscious people worldwide. Donations and optional paid licenses sustain continued development while the hardened privacy and protection core remains free. Premium adds professional workspaces and managed infrastructure without weakening the Free security baseline. A public warrant canary and live system-status page are maintained on kodachi.cloud.

No. All editions are free only for individual, noncommercial personal learning and research use; schools, employers and other organizations need a license. Commercial, professional, or organizational use requires a paid license (Premium or Custom), which include commercial usage rights. The feature comparison explicitly marks commercial use as not allowed on the Free tier.

Free includes the core privacy toolset, Circle and Lite Classic, the Simple and Direct startup screens, every appearance pack, one Default preference profile, current-session command and execution history, accessibility and performance controls, and the normal managed pool. Premium adds the Vitals system monitor, the top-level SOC dashboard, the ColonyOps operations workspace, the Advanced startup launcher and the VPN Providers and Mobile Manager pages in Lite Classic, multiple preference profiles, persistent history, the exclusive web services for domain security, DNS propagation and IP intelligence, commercial usage rights, priority triage, and low-density managed nodes with fewer users and a choice of exit IPs. Custom includes Premium plus custom-server operations, assigned isolated infrastructure, and direct written developer support (email and private Discord messages, 12 cases per organization per license year, no calls). The Free and Premium split is set on the Kodachi license server and shown live on the support page; a signed-in Kodachi 10 dashboard picks up a change within about ten minutes, and one that starts offline, or loses the Kodachi server for more than about half an hour, shows the built-in Free set until it signs in again.

The Free tier runs on high-density shared infrastructure with a monthly bandwidth allocation. When a shared node hits its monthly cap, service for that node pauses and resumes the next billing cycle or when capacity frees up. Paid plans have higher allocation and fewer users per node, so they are far less likely to be exhausted.

No. Premium and Custom are annual licenses: 12 months of all updates, including across major versions. A new major version that ships during your active license is included at no extra cost. After 12 months your last ISO keeps working; you renew only to keep receiving updates and managed-node access.

It is an annual license billed once, not an auto-renewing subscription - nothing recurs unless you choose to renew. Kodachi uses semantic versioning (Major.Minor.Patch); your active license covers 12 months of all updates, including across major versions (for example a 10.0.0 that ships during your term). After 12 months your last ISO keeps working; renew to continue updates and managed-node access.

License activation is managed by online-auth (Dashboard: About > License Manager). On the same active install on the same PC no release is needed. Before reinstalling or moving to another PC, release the license on the old system first, with the Release License button in the Dashboard or in the terminal with:

Then activate again on the new system. If you have already wiped the old machine, open the web License Portal (link on your purchase-complete page, or the link icon in Dashboard > About > License Manager), go to the Devices panel, click the release icon, type RELEASE to confirm, and the seat is freed immediately so you can activate on the new machine.

All cryptocurrency transactions are final and non-refundable, and no separate refund policy or money-back guarantee is described for any payment method. Treat purchases as non-refundable.

No. There is no SLA on any tier (Free, Premium, or Custom). The commitment is continuous updates, best-effort VPS availability, and infrastructure maintenance. Priority support means paid requests are triaged ahead of free ones on a best-effort basis only and does not constitute an SLA. Custom's direct developer support (12 written cases per organization per license year) is also best effort and carries no response-time guarantee.

No Kodachi account or conventional account fields such as name, email, or phone number are required, and the license key is delivered on screen. Payment providers still process the transaction data required by their services, while the site can observe request and network metadata. Monero can reduce payment metadata, but no payment method guarantees anonymity.

Custom is $600 per device per year with a minimum of 5 devices. The minimum exists because Custom includes a fully isolated VPS, and the baseline device count covers the infrastructure cost of that exclusive instance. Custom also includes direct written developer support (12 cases per organization per license year, no calls). By default all your devices (up to 100) run on a single isolated VPS with a default country and provider. If you want a specific country or provider, or want to isolate groups of devices on their own servers, your plan lets you split into up to one VPS per 10 devices, each provisioned in a country and provider of your choice (for example 20 devices on one server and 10 on another). Premium is $99 per device per year with no such minimum.

Binding microsocks/V2Ray to 0.0.0.0 makes the proxy reachable by every device that can route to the server - an open-relay risk. Kodachi's microsocks uses ports in the 30050-30054 range; restrict access with firewall rules that allow only trusted IPs and drop the rest, and isolate the proxy on a dedicated/segmented network.

You do not need a license for personal use - Kodachi is free for individuals, and donations are entirely separate from licensing (they do not grant license keys, Premium/Custom access). To donate any amount you like, use the Donate section of the support page - the same page used for license purchases. It offers direct cryptocurrency donations (Bitcoin, Monero, USDT and more, to reduce payment metadata) and the third-party services NOWPayments and Donorbox. Any contribution helps sustain the free personal-use tier and the shared VPS infrastructure.

Yes. Every paid license comes with a private web License Portal where you paste your license key (no account and no email needed, the key itself is your login) and instantly see everything about your purchase: your tier (Premium or Custom), how many seats you bought and which ones are activated, when your key expires shown as a countdown gauge, whether it is time-based or version-based, the devices it is active on, the price you paid and the purchase date, and your full transaction history and download links. If you have a group order with multiple keys, paste them all on separate lines and the portal displays all your licenses together in one view.

You can also release a license from the portal when you need to move to a new PC: find the Devices panel, click the release icon, type RELEASE to confirm, and the seat is freed immediately so you can activate on another machine. This is especially useful if you no longer have access to the old device.

The portal never shows your activation IP addresses. For security it is rate-limited: after 10 incorrect submissions it locks for 1 hour, and if you ever get stuck you can contact me on Discord or by email. You do not need to hunt for the address: the portal link is shown automatically on your purchase-complete page the moment your payment is confirmed. You can also open it directly from the Kodachi Dashboard (About, License Manager, then the link icon next to your key). Save it to your favourites and you can return to it anytime.

Yes. Beyond the standard tiers, Kodachi can produce a bespoke build as a paid service. A custom Live ISO can ship with the applications you choose pre-installed (for example ONLYOFFICE, Twinkle, Dolphin Anty, KolourPaint, or an Android emulator), with amnesic non-persistent behavior or as an installable image, with the installer enabled or fully removed so employees cannot install to disk, with additional system languages and locales (such as Ukrainian), and with configuration hardening to your specification. You can also have a private dedicated VPS provisioned in the country and with the provider you require (for example a specific NATO-member jurisdiction), running the protocols you choose.

The image ships with no personal accounts, browser sessions, saved passwords, or customer data baked in, is cryptographically signed, and boots reliably from USB SSD or USB flash on ordinary UEFI and BIOS PCs. Builds are produced for lawful, defensive, educational, and privacy-protection purposes. Tell me your requirements (a short, non-sensitive outline is enough to start) and I will study the scope and feasibility and send you a fixed, per-project price quote before any work begins. See the Custom ISO Builds & Private VPS section on the Support page for full details, and contact me on Discord at https://discord.gg/KEFErEx.

Update first, then search, then report. Many reports turn out to be fixed already, so install the latest updates (updating without a new ISO) and read the changelog, which lists what each update fixed.

Then search the Kodachi Discord's bug channels: #kodachi-bug-reports for the stable release and #k10-test-beta-bugs for beta builds. If you are not sure whether something is a bug or a setting, ask in #general-support first; that is often the faster answer (where to get help).

A report that can be fixed in one pass says which version and build you run, whether it is Live, installed or in a VM, the hardware, the dashboard you used and the steps you took, plus the exact error text or a screenshot. Check the version with:

When the developer needs to dig deeper, attach the Debug Collector's zip (sending logs); read what it removes and what it keeps before you share it (what the collector hides).

Do not pay again, and do not send more coins until you hear back. Contact the developer with your order ID and payment ID: the order is checked by hand and either completed, with your license details sent to you, or you are told the exact amount still due and how to pay it for the same order. The payment status page asks for the same thing (Partial payment received - please contact support).

Post in the support channel of the Kodachi Discord that your payment was partially received, and send the order ID and payment ID in a private message to the developer, never in a public channel (where to get help).

A short payment usually means the wallet or exchange took its network fee out of the amount you typed, or the payment arrived after the timer on the NOWPayments page ran out (about 20 minutes). Next time, send the exact amount shown, with the fee added on top, before the timer ends.