A full Debian 13 (Trixie) XFCE desktop transformed into a privacy command center, with a visual dashboard, browser tools, AutoShield guidance, and day-to-day privacy controls from a complete live or installed environment.
XFCE desktopDashboard modesAutoShieldTor / VPN / DNSLive or installed
Detached RSA-4096 signature files for OpenSSL verification are available on the Kodachi download page. Download the signature files from the same location:
kodachi-os-xfce-10.0.3-amd64.iso.sig.info - Signature information
Prefer browser-based verification? Use the File Verification tool to compute hashes and compare against all official Kodachi checksums automatically.
Kodachi is built and maintained by one person since 2013.
If this ISO is useful to you or your organisation, please
consider supporting the project
before you leave.
Installation Methods
Bare Metal - Install directly on hardware for maximum performance and daily use
Virtual Machine - Run in VMware/VirtualBox/QEMU for testing or isolated environments
Live USB - Boot without installation; session changes are not persisted to the live medium by default, while mounted disks remain writable
Persistent Storage - Enable persistence for configuration retention across reboots
Need boot-time LUKS nuke? Use the Debian installer from the ISO GRUB menu, not the normal GUI encrypted path. Boot the ISO, open Advanced options & fallback modes..., then choose Install Kodachi (Text + Full Disk Encryption, Boot-Nuke Compatible) or the unattended encrypted entry.
Those Debian-installer entries keep /boot outside LUKS so the passphrase prompt stays in initramfs, which is required for cryptsetup-nuke-password. The Calamares GUI installer is still fine for standard installs, but GUI encrypted installs may put the first LUKS prompt in GRUB, which blocks duress-at-boot nuke.
Keyboard layout during installation: by design, not a bug. Kodachi has two installers, and they handle the keyboard layout differently:
1. Text installer (the entries launched from the GRUB boot menu). The keyboard-layout prompt is deliberately disabled and the layout defaults to US English. This is intentional so the installation is fully unattended and works offline. There are no prompts for network, locale, or keyboard. The benefits: faster installation, no dependency on network/DHCP, no confusing prompts, and reliable operation in isolated/air-gapped environments. The only trade-off is that the keyboard defaults to US English during setup. This has nothing to do with saving space on the ISO. All keyboard layouts are still included, and you can switch to your layout (e.g. Spanish) at any time after installation with no issues.
2. Calamares graphical installer (available inside the live session once the ISO has booted). This installer does let you choose your keyboard layout and locale during installation. If you want to set your layout (e.g. Spanish) at install time, boot into the live desktop and run the Calamares installer instead of the text installer.
Either way, your installed system works perfectly with any layout. The only difference is whether you select it during installation (Calamares) or after first boot (text installer).
Login Credentials
Username:kodachi
Password:Security4All
These are the live-session kodachi account credentials. root login is disabled and does not use this password.
Single-OS USB creator from the YUMI team. Lightweight and reliable.
Linux (dd)Recommended
# Find USB device
lsblk
# Write ISO (replace /dev/sdX)
sudo dd if=kodachi-os-xfce-10.0.3-amd64.iso \
of=/dev/sdX bs=4M status=progress oflag=sync
macOS (dd)
# Find disk identifier
diskutil list
# Unmount and write ISO
diskutil unmountDisk /dev/diskN
sudo dd if=kodachi-os-xfce-10.0.3-amd64.iso \
of=/dev/rdiskN bs=4m
Double-check your target device. The dd command will overwrite the entire drive without confirmation. Use lsblk or diskutil list to verify the correct device before writing.
Why Kodachi Desktop
Kodachi Desktop is not a respin. It is a purpose-built operating system where every package, every configuration file, and every default setting was chosen with a single objective: uncompromising privacy for daily desktop computing.
Built over more than two years and based on Debian 13 (Trixie), Kodachi Desktop combines the terminal security stack with a complete XFCE desktop environment. The system bundles 482 curated packages: 266 terminal-level security and networking packages plus 216 desktop GUI applications, each serving a specific privacy role. Fully resolved with dependencies, the 10.0.3 desktop ISO installs 2,919 packages.
The desktop ships with a dark theme (LK_Material-Black-Lime) optimized for operational security. Under the hood, Kodachi binaries form a unified security control plane managed through the Kodachi Dashboard.
Privacy by Design
Kodachi Desktop boots with its privacy defaults already in place: encrypted DNS and randomized MAC addresses from the first boot. You then choose the route, a VPN protocol, Tor, or both layered, from the dashboard or the command line.
14 Selectable Routing Paths
The routing service scores 14 routing protocols, of which plain auto-select ranks 12: AmneziaWG and OpenVPN over Cloak are opt-in and only enter the ranking with --prefer-obfuscated, and xray-vmess is a legacy factory fallback. AmneziaWG and OpenVPN over Cloak are censorship-resistant variants of classic VPN protocols. Supported underlays can be layered with system-wide Tor routing via tor-switch torrify-system-nftables-dns. Layering changes route topology and can increase latency; it does not guarantee anonymity or prevent traffic correlation.
DNSCrypt Auto-Config
Encrypted DNS is on from the first boot: dnscrypt-proxy answers on 127.0.0.1, /etc/resolv.conf points to it and systemd-resolved stays disabled. No manual configuration required, and dns-switch changes the resolver whenever you want.
MAC Randomization
NetworkManager presents a randomized MAC address on every Wi-Fi and wired connection, stable for one network during one boot and different across boots, and Wi-Fi scans use random addresses. health-control changes or resets MAC addresses on demand.
Changed default: the DHCP client identifier and the IPv6 DHCP identifier now follow the randomized MAC instead of the machine ID, so a DHCP server sees a new client after each boot, as it already sees a new MAC.
No TCP Timestamps
Changed default: from the first boot the kernel leaves timestamps out of TCP connections (net.ipv4.tcp_timestamps = 0), which removes an uptime and clock fingerprint that remote hosts could read. Nothing changes in normal use.
Hardware Wallets
Ledger and Trezor devices work for the signed-in user without root, so wallet apps can reach them as soon as they are plugged in.
Kill Switch & Leak Response
Triggering the kill switch, by hand or from the Panic Room, runs panic level medium: it sets the IPv4 firewall to drop everything, stops NetworkManager, Tor and OpenVPN, takes every network interface except loopback down (so IPv6 stops with the links), terminates running processes, clears memory caches and the clipboard, unmounts removable devices and locks the screen. Arming it only raises a high-alert flag; it does not watch the tunnel. routing-switch tears a connection down when it detects an IPv6 leak. WireGuard and OpenVPN replace the default route, so traffic stops if the tunnel drops. The tun2socks-based proxy protocols prefer the tunnel but keep the original gateway as a high-metric recovery route (in --metric mode as a regular fallback), so if the tunnel process dies, traffic can leave through it. Check the route status after any interruption.
System Hardening
Kodachi Desktop applies defense-in-depth from the kernel upward. Mandatory access controls, file integrity monitoring, audit logging, device whitelisting, and application sandboxing create a layered security posture.
AppArmor
Mandatory access control that confines critical applications to minimum required permissions. Profiles restrict file access, network capabilities, and system call usage per application.
AIDE
File integrity monitoring with cryptographic hash detection. Maintains a baseline database of system files and alerts on unauthorized modifications, additions, or deletions.
auditd
System call recording, file access logging, and privilege escalation tracking. Writes tamper-resistant audit logs for forensic analysis and compliance reporting.
Firejail
Application sandboxing with separate filesystem namespaces and network stacks, confined by its own AppArmor profile. Kodachi uses it for the sandboxed file manager, and you can start any application inside a Firejail profile.
Portmaster
Application-level firewall and network monitor from Safing. Provides per-application traffic visibility and policy enforcement through a desktop UI and system service.
Secure Boot
UEFI Secure Boot with signed GRUB and shim packages. Verifies bootloader integrity before execution, preventing rootkits and unauthorized boot-time modifications.
Security Models & Layered Anonymity
Kodachi Desktop includes 122 pre-built workflows plus custom workflows via workflow-manager. Below are 18 illustrative templates covering WireGuard, OpenVPN, Shadowsocks, Hysteria2, V2Ray, Xray, and Mita. Their tier labels describe increasing route layering, not a guarantee of anonymity. More layers add complexity and latency, while endpoint trust and traffic-correlation risks remain. Profiles are stored in /opt/kodachi/dashboard/hooks/config/profiles/.
Designed for: High-risk work where layered routes reduce single-provider exposure. This configuration does not guarantee anonymity or safety against a state-level adversary.
Designed for: High-risk reporting and research where layered routes may reduce single-provider exposure. Operational security and endpoint behavior remain essential.
Kodachi VPN (Hysteria2/V2Ray/Shadowsocks) → Torrified System → Tor DNS
Tier 6Moderate Anonymity, Single VPN OnlyWorkflow 18
Anonymity: Moderate (3/5)Speed: Fast
Layer
Single VPN with encrypted DNS
Best for
Online banking, shopping, business email, general secure browsing, fast performance requirements
Chain
Kodachi VPN (OpenVPN) → DNScrypt
Create Custom Workflows using workflow-manager for: Multi-protocol chains, adaptive failover, custom threat models, automated security responses, and specialized use cases.
NOT Recommended: Tor → VPN
Avoid Configuration: Your Computer → Tor → VPN → Internet
This configuration is widely discouraged; it blocks .onion access, lets the guard see your real IP, makes Tor usage detectable, degrades performance, and shifts trust to the VPN.
Why this is dangerous: Entry nodes see your real IP • ISP detects Tor usage • NO access to .onion sites • Severely degraded performance • VPN provider can see your activity
Based on Privacy Guides 2025 recommendations, Tor Project documentation, and Kodachi security research. The tier names describe route-layering goals, not guarantees; endpoint, fingerprinting, malware, and traffic-correlation risks remain.
System Hardening & Security Score
Kodachi calculates a real-time Security Score (0-100) across seven weighted categories with an adaptive denominator that excludes checks your hardware or session cannot satisfy. Seven hardening modules can be applied independently, and three hardening profiles (standard, medium and paranoid) apply them in increasing strength.
Security Score
90-100
Excellent
75-89
Good
60-74
Fair
40-59
Partial
0-39
Critical
Category
Weight
What It Measures
System Security
30 pts
Disk encryption (LUKS), firewall, swap encryption, auto updates, Secure Boot, kernel hardening, AppArmor/SELinux
Privacy & Anonymity
25 pts
Tor and torrification, DNS privacy, VPN or proxy, browser privacy, MAC randomization
Network Security
20 pts
Kill switch, DNS leak protection, network hardening, port security, IPv6 privacy
auditd activation, authentication-event and system-integrity checks, file integrity baselines from the medium profile up (AIDE when installed), and LKRG at paranoid. Rootkit and virus scans run as their own commands.
The default, and nothing breaks. Safe kernel sysctls, secure filesystem mounts, full ASLR, symlink and hardlink protection, SYN flood protection, auditd monitoring and AppArmor/Firejail detection. Safe with every browser and with VPN and Tor routing. sudo health-control security-harden --profile standard
Medium
Standard plus hidepid=2 on /proc, hardened_malloc, dirty-page tuning and file integrity monitoring. Browsers and the internet keep working; on LUKS systems hardened_malloc raises memory use. sudo health-control security-harden --profile medium
Paranoid
Medium plus disabled user namespaces and IP forwarding, MAC spoofing, a DNS firewall, LKRG, Tirdad, SMT off and RAM wipe. It WILL break browsers, internet access and VPN/Tor routing, and without user namespaces oniux, browser sandboxes and bubblewrap stop working. --break-monitoring applies paranoid and also makes /sys/class/net root-only, which breaks conky and dashboard monitoring. Undo with sudo health-control security-recover.
Integrated Security Tools
Kloak
Keystroke anonymization. Randomizes key event timing to defeat keystroke-timing analysis, which makes typing-rhythm fingerprinting far harder.
Tirdad
TCP ISN randomization kernel module. Prevents TCP/IP stack fingerprinting by randomizing Initial Sequence Numbers. Anti-fingerprinting at the protocol level.
Note: Tirdad requires a boot mode without module.sig_enforce=1 or lockdown=integrity. Safe modes: Kodachi Live, Persistent, Encrypted Persistence, CPU Hardened, DMA Protection, Hardened Malloc, Full RAM mode, Performance Balanced and the hardware-compatibility entries. Not available on the four entries that enforce module signatures: Maximum Privacy, Kernel Lockdown (confidentiality), Forensics Mode and Full Hardening. (Forensics Mode joined that list on 2026-09-04, when the tiers were made a strict superset chain and it gained lockdown=integrity; the tier-4 lockdown entry was also renamed that day to "Kernel Lockdown (confidentiality)", because it is the kernel lockdown LSM and not the UEFI firmware feature.) On installed systems the same four block unsigned modules.
"Blocked" on hardened modes is correct, fixed behavior (not a bug). Older ISOs falsely reported Tirdad as "ENABLED" even though it never actually loaded on hardened modes. Current ISOs tell the truth: the hardened boot modes (Kernel Lockdown (confidentiality), Full Hardening, Maximum Privacy and, since 2026-09-04, Forensics Mode) enforce signed kernel modules, and Tirdad ships as an out-of-tree DKMS module signed with a certificate generated during the Kodachi build, which no machine trusts (it is not part of the mainline signed kernel), so the kernel refuses to load it by design. To run Tirdad, reboot into a non-signature-enforcing mode (Kodachi Live, Persistent, Encrypted Persistence, CPU Hardened, DMA Protection, or any of the hardware-compatibility entries). There it loads and shows ENABLED / Module Loaded: YES.
Why this happens: hardened modes turn on kernel module signature enforcement (module.sig_enforce=1 / lockdown), which is itself a security-hardening measure that stops the kernel loading any module that is not signed by a key it trusts. The locked-down kernel refuses Tirdad not because Tirdad is bad, but because it cannot verify its signature against a trusted key, the same way it would block any third-party module. It is a trade-off between two good things: kernel-integrity lockdown vs. one extra privacy module. On hardened boot you get the stronger kernel lockdown; on Tier 1-3 modes you can run Tirdad instead. You are not losing meaningful protection either way, as the hardened modes already harden TCP/networking through other means.
The security score no longer penalizes you for Tirdad on hardened modes. It is marked N/A there, so nothing is wrong on your end.
Secure Boot: if UEFI Secure Boot is enabled in your firmware, the kernel enforces module signatures and Tirdad will not start enabled until your signing key is enrolled. The Secure Boot Guide gives the steps. The other way is to disable Secure Boot in your BIOS/UEFI firmware settings.
AIDE
Advanced Intrusion Detection Environment. Monitors file integrity by comparing file hashes against a known-good database. Detects unauthorized modifications.
Rootkit Scanning
Dual-engine scanning with rkhunter and chkrootkit, both preinstalled, through sudo health-control rootkit-scan-enhanced (or the quick rootkit-scan). Looks for kernel rootkits, backdoors and hidden processes.
ClamAV
Open-source antivirus engine for on-demand scans through sudo health-control clamav-scan (Virus Scan in the dock), with optional quarantine. ClamAV is not preinstalled in the 10.0.3 ISO; install it first with sudo apt install clamav.
Kodachi Dashboard
Five Cockpits. One Mission. Total Control.
The Kodachi Dashboard orchestrates 606 commands registered across 26 CLI services and provided by 25 command-bearing binaries, with zero GUI freezing. Choose your cockpit: Circle (gamified security ring, free), Lite Classic (the main categorized dashboard, free), Vitals (live system monitor, premium), SOC (live security monitor, premium) and ColonyOps (workflow and operator mode, premium). A first-boot AutoShield wizard runs before you pick one.
Routing Guide
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 such as speed, account safety, censorship resistance, DNS privacy, and layered anonymity.
Use it when you are unsure whether you need WireGuard, OpenVPN, the censorship-resistant variants AmneziaWG and OpenVPN over Cloak, other anti-censorship transports, Tor, DNSCrypt, or a workflow-backed layered setup. The wizard lists AmneziaWG and OpenVPN over Cloak when your account card carries them, and leaves them out when it does not. The guide narrows the dashboard's large routing surface into recommendations that explain why a route fits, what you give up for more or less protection, and who can still see what.
For new users, this makes the dashboard easier to understand without learning every binary first. For experienced operators, it reduces mistakes such as picking the wrong route for logged-in accounts, changing protocols blindly, or combining VPN and Tor in the wrong order. In short: the Routing Guide helps you use Kodachi more safely, with a clearer mental model of what each routing choice actually does.
Quick Launch, the Startup Picker
Before the dashboard opens, the Quick Launch picker asks which cockpit you want, grouped the way the cockpits behave: the control cockpits first, then the monitor cockpits. The on-screen order is Circle, Lite Classic, ColonyOps, Vitals, SOC, and the number keys 1 to 5 pick them in that same order.
The picker is not a one-time decision. Once a cockpit is open you can switch at any time from the Dashboards button on the left rail, which every cockpit shares. Cockpits you have not activated are shown locked rather than hidden, so you can always see what the premium tier adds.
CIRCLE MODE
DEFAULT
Gamified Security Ring
Restores to 1400×1000
~230MB RAM
Beginner to Advanced
Interactive circular interface with 7 clickable security arcs surrounding a central hub showing real-time IP, country flag, and security score (0-100 with color-coded risk levels).
7 Security Arcs: Authenticate, MAC Randomize, Hostname Spoof, Random Timezone, DNSCrypt, WireGuard VPN, Torrify System
Victory Animations: Celebrate security milestones at 25%, 50%, 75%, and 100% completion
Dual Auto-Refresh: 30s for IP/status checks, 60s for deep metrics with pause/resume controls
Countdown-driven setup wizard presented as a tab on the dashboard's welcome screen on first boot. Configures anonymity layers, randomizes system identity, and establishes secure connections with real-time telemetry and protection level visualization.
Automated Security Setup: VPN protocol selection, Tor configuration, DNSCrypt activation, and MAC randomization in one guided flow
Countdown Timer: Auto-executes security configuration after countdown, with manual override for custom setup
Protection Level Viz: Real-time system telemetry with security score, IP geolocation, and connection status indicators
Binary Verification: Validates all bundled core binaries, authenticates session, and collects system status on first run
30Controls
8Categories
AnyWorkflow Profile
~180MB RAM
LITE CLASSIC
Compact Command Center
Restores to 1400×980
~300MB RAM
Beginner to Advanced
Grouped sidebar of 16 pages in three groups (Overview, Essentials, Command & Monitor) covering security operations, AI chat, the command library and builders, system monitoring, and terminal tools with live output display. Fourteen pages are free; VPN Providers and Mobile Managerunlock with Premium.
16 Sidebar Pages: Actions, Health, AI Chat; Tools, VPN Providers, Mobile Manager, Hardening, Passwords, Tor Essentials, DNS Essentials, Workflows, Emergency, AI Commander; Command Library, Command Builder, Monitor
Grid/List Toggle: Two visualization modes for command output with syntax highlighting and error detection
Live Metrics Footer: Real-time CPU usage, memory consumption, and network throughput monitoring
589Presets
3Groups
16Pages
~300MB RAM
VITALS COCKPIT
Live System Monitor
Restores to 1400×1020
~240MB RAM
Monitoring
Premium monitoring cockpit that keeps the machine's live readings on screen and refreshes them while the window stays open. It is the genuinely read-only cockpit: nothing in it changes system state.
Live readings: continuously refreshed gauges, histories and status tiles for the running system, with no page reload and no manual polling
Tor and leak panels: the live Tor circuit hop by hop with country, how many onion services you publish and which ones no longer answer, and a UDP leak check that runs only when you press it
No routing controls by design: carries no VPN, DNS, Tor or hardening controls, so it can be left open on a shared screen without exposing an action
Premium cockpit:unlocked with a Premium or Custom license key. opens on every plan. Cockpits you have not activated are shown locked rather than hidden
PremiumTier
MonitorGroup
Read-onlyAccess
~240MB RAM
SOC COCKPIT
Live Security Monitor
Restores to 1400×1020
~240MB RAM
Monitoring
Premium security cockpit built on kodachi-soc. A neural map groups the host's security telemetry into ten cluster hubs and keeps them live while you watch.
Host exposure WATCHER: enables and disables the host-exposure systemd unit, and kodachi-soc-notifier delivers bounded local session notifications for its findings
LAN WATCH: a timed, listen-only watch of the local network (10 to 600 seconds) for ARP spoofing, rogue DHCP servers, rogue IPv6 routers and port scans; it sends nothing and blocks nothing
IDENTITY ALERTS: changes to accounts, sudo rules, SSH keys, SSH server settings and setuid programs, recorded by the SOC watcher; changes made by package installations are kept quiet, the watcher never blocks a change, and it records only while it is turned on (it is off by default: turn it on from the SOC page); when it is off the page says so instead of showing an empty list
Published onion services: every onion service this machine publishes appears in the Network hub and in the Host Exposure window, and one whose local service no longer answers is a warning
Exposure findings: read the live summary and history and acknowledge a finding from the cockpit; reviewing, approving and revoking policy stays on the command line (sudo kodachi-soc policy). It carries no VPN, DNS, Tor or hardening controls
PremiumTier
MonitorGroup
10Cluster Hubs
~240MB RAM
COLONYOPS COCKPIT
RECOMMENDED
Workflow and Operator Mode
Restores to 1280×860
~260MB RAM
Intermediate to Expert
Premium operator cockpit that mounts 1030 command cells in one working surface, for people who already know what they want to run and want it one click away.
1030 Mounted Cells: the full command surface laid out as cells you arrange around your own workflow rather than a fixed tab order
Signed binary suite: complete access to health-control (255 commands), tor-switch (127 commands), routing-switch (31 commands), dns-switch (45 commands), online-auth, workflow-manager, and more
Control cockpit: unlike Vitals and SOC this one acts on the system, so it carries the same danger badges and authentication prompts as Lite Classic
PremiumTier
1030Mounted Cells
26Services
~260MB RAM
Core Infrastructure Across All Modes
All five cockpits share the same powerful backend: 606 commands registered across 26 CLI services and provided by 25 command-bearing binaries, with async execution to prevent GUI freezing. Security score aggregates 7 weighted categories (System Security, Privacy & Anonymity, Network Security, Authentication, Device Security, Advanced Privacy, Data Protection) with five color-coded tiers: Excellent (90+), Good (75-89), Fair (60-74), Partial (40-59), Critical (<40). The denominator is adaptive: checks that cannot apply on the running system (e.g. disk encryption on a live ISO, Secure Boot on BIOS) are excluded rather than counted as failures.
Async Execution
Danger Level Badges
4 Output Formats
Auto-Refresh
IP + Flag + Auth Status
Mode Switcher
Cockpit Comparison Matrix
Cockpit
Restore Size
RAM Usage
Interface
Skill Level
Tier
Circle
1400×1000
~230 MB
Sliced command wheel (7 segments)
Beginner to Advanced
Free
Lite Classic
1400×980
~300 MB
611 dispatchable commands
Beginner to Advanced
Free
Vitals
1400×1020
~240 MB
Live system monitor (read-only)
Monitoring
Premium
SOC
1400×1020
~240 MB
Live security monitor
Monitoring
Premium
ColonyOps
1280×860
~260 MB
1030 mounted cells
Intermediate to Expert
Premium
Connectivity Highlights
Recent desktop builds added practical fallback networking tools directly into the dashboard, exposing VPNGate access and a step-by-step recovery flow without dropping to the terminal.
Essentials > Actions > Connection > VPNGate
Built-In
The dashboard now includes a full VPNGate public server browser inside the Connection block, so free OpenVPN fallback routes are available even when your usual provider is down.
Fetch and cache live public servers directly from the VPNGate API
Filter by country and cycle sort by speed, ping, score, or sessions
Connect in-place or export one or all .ovpn profiles for external OpenVPN clients
Essentials > Actions > Network Recovery > Fix Internet Wizard
Guided Repair
A floating repair wizard now opens from the recovery block and runs through real diagnostics before changing anything.
Pre-checks routing, DNS configuration, DNSCrypt, torrify state, ping, DNS lookup, and HTTP reachability
Starts with normal recovery steps: full auto recovery, DNS cache flush, fallback DNS, and forced DNS repair
Expands into advanced routing reset/recover, DNS mode toggle, DNSCrypt restart/remove, and full detorrify when needed
Lite Dashboard Recovery + VPNGate Shortcuts
Fast Access
Lite Classic mirrors the same fallback logic for operators who want one-click recovery and temporary backup tunnels without leaving the cockpit.
VPNGate Free VPN includes rank-based Connect #1-#10, sort views, and Export All Profiles
Quick Recovery exposes Fast Recover, Recover Internet, and Routing Recover
Useful as a fallback path when your primary tunnel is broken or your normal provider is unreachable
Dashboard Hints & Tips
The operator field manual for the Kodachi Dashboard. Click any section to expand it. Every path uses the real GUI labels so you can go straight to the feature.
Top Status Bar & Panel Controls
11 tips
Top Status Bar > AI Chat Button
Opens the AI assistant popup over your current view. Ask for guidance, command syntax, or troubleshooting help without switching tabs. Available in every mode including Circle.
Top Status Bar > Clapperboard Icon
Toggles all dashboard animations on or off instantly. One click when the interface feels heavy, does not change the Performance mode setting, just a quick override you can flip back any time.
Top Status Bar > Compact Mode Icon
Hides side panels to create a minimal workspace. Useful on small screens or when you need the dashboard visible but out of the way. Re-click to restore panels.
Top Status Bar > Auth Toggle
Login or logout of Kodachi cloud services. Controls access to premium features like VPN routing, identity randomization, and the full AutoShield step set. The auth state indicator updates across all tabs in real time.
Top Status Bar > Mode Selector
Shows which cockpit you are in: Circle, Lite Classic, Vitals, SOC or ColonyOps. To change cockpit, use the Dashboards button on the left rail, which every cockpit shares: move between quick setup, the classic dashboard, the two monitors and the operator cockpit at any time without relaunching. Cockpits you have not activated are shown locked rather than hidden, and your last selection is remembered across sessions.
Top Status Bar > Sparkles Icon
Opens the AutoShield wizard tab. Re-opens the first-boot automation wizard inside the running dashboard. Use this whenever you want to re-run the multi-step security hardening sequence.
Service Panel Header > Grid / List Icon
Toggles between Quick Actions (grid of one-click buttons) and Command Builder (full parameter form). Quick Actions for speed; Command Builder when you need flags, arguments, or custom parameters.
Service Panel Header > Help Icon
Opens context-aware documentation for the currently active tab. Each service tab has its own help content. The help icon adapts so you never have to search the wiki for the feature you are already looking at.
Output Header > Swap Icon
Swaps the output panel with the top status bar; you can also drag the status bar onto the output header. Put output on top if you spend more time reading it than issuing commands.
Output Header > Collapse Icon
Collapses the output window to its header to save screen space, and expands it again; the hide button closes it. Expand it when reviewing large JSON output or multi-line tables.
Top Status Bar > Draggable Chips
The status indicator chips (VPN, Tor, KNet, speed, etc.) in the top bar are draggable. Drag them to reorder the bar layout to your preference. The order persists across sessions so your most-used indicators stay front and center.
Lite Sidebar, 16 Pages in 3 Groups
14 tips
Overview > Actions
The main operator fast lane. This single tab bundles authentication, DNS, Tor, identity randomization, power controls, the unified Connection section, and the full Network Recovery block. Best starting page for daily operations when you need to act quickly.
Overview > Actions > Connection > VPNGate
Switch the Connection block from Protocols to VPNGate to browse public fallback VPN servers inside the dashboard. Use Fetch Servers, filter by country, cycle sorting between speed, ping, score, and sessions, then either connect directly or export reusable .ovpn profiles.
Overview > Actions > Network Recovery > Fix Internet Wizard
Opens the guided repair overlay with live checks for routing, DNS config, DNSCrypt, torrify state, IP reachability, domain resolution, and HTTP access. Start with the default queue, then expand Advanced Steps for routing recovery, DNS mode switching, DNSCrypt repair, or Detorrify system. Steps can be reordered, disabled, skipped, or retried.
Essentials > Tools
Oniux Tor isolation for a single application, multi-service paste, a Bitcoin balance lookup, and curated hostname and timezone pickers.
Essentials > VPN Providers (Premium)
The external VPN provider catalog: VPN Gate and Riseup with no account, NordVPN, IVPN, PIA, Surfshark and Mullvad with your own credentials, AirVPN, ProtonVPN, ExpressVPN, TorGuard and Windscribe through an imported config, plus paste-your-own profiles.
Essentials > Mobile Manager (Premium)
QR codes, share URIs and phone configuration exports for your routes, plus the Auth Card with your VPS services and credentials.
Essentials > Hardening
Six sub-tabs: Posture, Features, Advanced, USB, Batch and Commands. Features holds the individual toggles in six groups: Internet Control, Hardware Devices, System Services, Security, Privacy and Performance. Toggle only what your threat model needs; the strongest settings break everyday use.
Essentials > Passwords
Password generators with configurable length, character sets, and strength meters. Generate credentials for VPN configs, encrypted volumes, or service accounts without leaving the dashboard.
Essentials > Tor Essentials
Tor instance overview, exit-node country selection, circuit management, a live circuit view (guard, middle and exit relay with country), onion services (publish a service on this machine as a .onion address and check that it is reachable), bridges with obfs4, Snowflake, meek or WebTunnel, and quick torrification controls. Daily Tor operations without opening Command Builder > Tor Switch.
Essentials > DNS Essentials
Active DNS server display, DNSCrypt toggle, Pi-hole status, and DNS health checks. Verify encrypted DNS is active and leak-free after any routing change.
Essentials > Workflows
Workflow automation builder for multi-step command sequences. Create repeatable playbooks like "morning startup" (auth, VPN, DNS, harden) or "pre-meeting lockdown" (torrify, rotate MAC, flush DNS).
Command & Monitor > Command Library
Searchable command library across all 606 commands registered under 26 CLI services and provided by 25 command-bearing binaries. Type a keyword like "leak" or "hostname" and the library shows every matching command with its service, danger level, and description.
Essentials > Emergency
Kill Switch, Nuke, the three panic levels, proxy and firewall controls, integrity verification, secure wipe tools and the shutdown policy. If something goes wrong, start here.
Essentials > AI Commander
AI Commander (natural-language command interface) and AI Daemons (background monitors). Describe what you want in plain language and the AI translates it into the correct binary commands.
Security Scoring Explained
Understanding the 100-point system
You Do NOT Need a High Score to Be Secure
A score of 60-75 (Fair to Good) is perfectly adequate for daily use. The higher you push the score, the more things may stop working for normal browsing and daily tasks.
Features like disabling WiFi, blocking USB, killing Bluetooth, and full kernel hardening are designed for HIGH-THREAT scenarios such as journalists in hostile countries, whistleblowers, and one-time sensitive operations. For a daily driver, you want MODERATE security that balances privacy, security, and stability.
Combining aggressive features like Secure Boot + LUKS + full hardening + Tor can cause breakage: services may fail, hardware may not be detected, boot times increase significantly. A score of 50-65 with VPN + DNSCrypt + firewall active is already far more secure than 99% of operating systems. Only push to 90+ if you are protecting something truly critical and accept that convenience will suffer.
How the Scoring Works
The security score is calculated by sudo health-control security-score on a 100-point scale across 7 categories with an adaptive denominator. Context detection skips checks that physically cannot apply: headless systems skip Bluetooth/webcam, WiFi-only systems skip WiFi, live-ISO sessions skip disk encryption / swap encryption / auto-updates / backup / encrypted-container checks, BIOS-only machines skip Secure Boot, and systems without swap skip swap encryption. Excluded checks drop out of the maximum rather than counting as failures, so the displayed total may read e.g. 57 / 82 instead of 57 / 100. VPN/proxy and Tor are scored independently; running both stacks them additively (++).
Live ISO vs Installed: both can reach 100%. The score is a percentage of applicable points, not absolute points. 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 live user who maxes every applicable check still reaches 100. On an installed system those same checks become active. Enable LUKS at install time, keep auto-updates on, encrypt your swap, and the installed ceiling is the same 100. An installed system without LUKS scores lower than the same-effort live session because the disk-encryption check is now applicable and failing, which is correct: an unencrypted disk is genuinely less protected. Kodachi does not penalise USB-boot users and does not reward installation by itself. Only enabling more applicable protections raises the score.
Per-check Applicability Matrix
✓ means the check counts toward the maximum and can earn points. N/A means the check is skipped on that system and drops out of the denominator (it cannot be a failure). Conditional applicability is noted inline.
Category / Check
Pts
Installed
Live ISO
Privacy & Anonymity (25 pts)
VPN / Proxy
6
✓
✓
Tor + Torification (graded)
8
✓
✓
DNS Privacy
7
✓
✓
Browser Privacy
2.5
✓
✓
MAC Randomization
1.5
✓
✓
System Security (30 pts)
Disk Encryption (LUKS)
8
✓
N/A
Firewall
8
✓
✓
Swap Encryption
4
✓ if swap
N/A
Auto Updates
4
✓
N/A
Secure Boot
3
✓ if EFI
✓ if EFI
Kernel Hardening
2
✓
✓
AppArmor / SELinux
1
✓
✓
Network Security (20 pts)
Kill Switch
6
✓
✓
DNS Leak Protection
5
✓
✓
Network Hardening
4
✓
✓
Port Security
3
✓
✓
IPv6 Privacy
2
✓
✓
Authentication (10 pts)
Auto-login disabled
3
✓
✓
2FA
3
✓
✓
GPG keys
2
✓
✓
Password Manager
2
✓
✓
Device Security - 5 pts (category rescaled to full budget when at least one check applies)
Bluetooth
N/A
✓ if GUI
✓ if GUI
WiFi
N/A
skipped if wifi-only
skipped if wifi-only
USB Storage
N/A
✓
✓
Webcam
N/A
✓ if GUI
✓ if GUI
Microphone
N/A
✓ if GUI
✓ if GUI
Advanced Privacy (5 pts)
Tirdad
1
✓
✓
RAM Wipe
1
✓
✓
Kloak
0.5
✓
✓
Metadata Cleaner
1
✓
✓
Telemetry Disabled
1.5
✓
✓
Data Protection - 5 pts (category rescaled to full budget when at least one check applies)
Encrypted Containers
2
✓
N/A
Secure Deletion
1
✓
✓
Backup Encryption
1
✓
N/A
Privacy Tools
1
✓
✓
Effective ceilings: the denominator follows your hardware, so the percentage is what counts. The numbers below assume every applicable check is maxed.
Installed on BIOS (no EFI) with LUKS: 97 / 97. Secure Boot drops out (3 pts), still 100% in percentage terms
Installed (EFI) without LUKS: caps at roughly 92%. That 8-point gap is the real cost of an unencrypted disk
Live ISO with EFI: 84 / 84. Reaches 100% when fully hardened (live drops 16 of the nominal 30 System Security points: Disk Encryption 8 + Swap Encryption 4 + Auto Updates 4)
Live ISO on BIOS (no EFI): 81 / 81. Secure Boot also drops out, still 100% when fully hardened
The unencrypted-disk penalty does not exist on live ISO because there is nothing to encrypt. Kodachi does not reward USB-boot users, it simply does not penalise them for a check that physically cannot apply.
1. Privacy & Anonymity (25 points max)
Tor + Torrification (8 pts): Tor active AND system torrified
Foundational protections in place; several optional layers still off
0-39% - Critical
Significant vulnerabilities
Recommended Security Profiles
Balanced (Target 70) - DEFAULT
Best for daily use. VPN + firewall + DNS encryption. Good security without breaking normal workflows.
VPN active, DNSCrypt enabled, firewall on, auto-login disabled
Paranoid (Target 95) - HIGH THREAT
For one-time critical operations. Everything maxed. Expect breakage and reduced usability.
All hardening enabled, Tor + VPN, USB blocked, WiFi/BT off, full kernel hardening
Minimal (Target 50) - TESTING
Bare minimum protections. Firewall + auto-login disabled. Use for compatibility testing.
Firewall active, auto-login off, no VPN/Tor, basic DNS only
Pro Tip: Run sudo health-control security-score to see your current score and detailed breakdown. The score is percentage-based: (earned points / applicable maximum) × 100.
System Monitor, 7 Subtabs
7 tips
Monitor > Resources
CPU usage, memory consumption, disk usage per partition, disk health (SMART), boot logs, and X server logs. First stop for diagnosing slowness or boot problems.
Monitor > Processes
Running process list with PID, CPU%, memory, and command line. Spot suspicious or resource-hungry processes. If an unknown process is using network, investigate immediately.
Monitor > Network
Active connections with local/remote address, port, protocol, and state. After enabling Tor, all traffic should go through 127.0.0.1 Tor ports. Any direct external connection is a leak.
Monitor > Firewall
Active firewall rules (nftables/iptables) in readable format. Confirm kill-switch rules are in place after hardening. Check that no unexpected ACCEPT rules appeared.
Monitor > Startup
Boot services (systemd units) with enabled/disabled status. Disable unnecessary services that start at boot. Fewer services means a smaller attack surface and faster boots.
Monitor > Logs
System logs (syslog, auth.log, kernel messages) with filtering. Review authentication attempts, kernel warnings, and service failures after security incidents.
Monitor > Terminal Tools
TUI-style diagnostics: speedtest (bandwidth), vnstat (traffic stats), local ports (listening services). Run a speedtest to verify VPN throughput or check vnstat for interface data.
Command Builder Tabs, Lite Classic
14 tips
Routing Switch routing-switch
14 scored protocols, of which plain auto-select ranks 12 (AmneziaWG and OpenVPN over Cloak need --prefer-obfuscated, and xray-vmess is a legacy fallback). WireGuard, AmneziaWG, OpenVPN, OpenVPN over Cloak, Shadowsocks, V2Ray, Xray (VLESS/Reality/Trojan/VMess legacy), Hysteria2, Mieru, Dante, Tor routing, protocol benchmarking, config export/QR tooling, plus the new External VPN Providers catalog (13 entries: VPN Gate, Riseup, NordVPN, IVPN, PIA, Surfshark, Mullvad, AirVPN, Windscribe, ProtonVPN, ExpressVPN, TorGuard, plus a "custom" pseudo-provider that auto-detects pasted .ovpn / WireGuard / Shadowsocks / V2Ray / Hysteria2 configs and vless:// links, all connectable; vmess:///ss:///trojan:///hysteria2:///tuic:// links and Clash YAML or sing-box JSON subscriptions import for browsing, and connecting those needs a sing-box sidecar that does not ship yet, except the OpenVPN and WireGuard entries of a subscription). Action chips for Fastest / Random connect, Resolve countries (via ip-fetch), Resolve IPs (DNS), and a manual Test latency that pings each cached server. The main workbench for switching transport layers.
Tor Switch tor-switch
127 commands. Tor instances, exit-node country selection, load-balanced torrification, circuit rotation, a live view of each circuit's relays, onion services you host, bridges (obfs4, Snowflake, meek, WebTunnel), and system-wide DNS-through-Tor. Deeper control than Essentials > Tor Essentials.
DNS Switch dns-switch
45 commands. DNSCrypt configuration, resolver switching, Pi-hole integration, random DNS selection, Tor DNS routing, and DNS health diagnostics.
DNS Leak dns-leak
DNS leak detection tests. Verify that DNS queries are not bypassing your VPN or Tor tunnel, and run the UDP leak test for other UDP traffic (WebRTC, calls, games) that could leave outside it. Critical after any routing change.
Health Control health-control
255 commands. Identity randomization, internet recovery, security hardening, panic modes (soft/medium/hard), kill switches with a Tor firewall watch, USB protection, memory wiping, firmware and platform checks, a read-only system doctor and boot-readiness check, and scoring.
Multi-provider IP geolocation with fallback. Verify your visible IP, country, ISP, and whether flagged as a known VPN/Tor exit.
Online Info online-info-switch
System information feeds: version checks, server status, update notifications.
Integrity Check integrity-check
Verify file signatures and hashes for all Kodachi binaries. Detect tampering or corruption. Run after system updates.
Permission Guard permission-guard
Monitor and enforce file permissions. Scan for permission drift on sensitive files (keys, configs, credential stores).
Workflow Manager workflow-manager
Create, edit, and execute multi-step automation workflows. Advanced version of Essentials > Workflows with full parameter control.
Global Launcher global-launcher
Binary deployment, verification, and cleanup for global symlinks. Manages installation of Kodachi binaries into system paths, verifies integrity, and handles uninstallation.
Kodachi AI kodachi-ai
AI integration hub: AI Commander, background daemons, and autonomous agent configuration.
Deps Checker deps-checker
Verify all system dependencies are present and correct. Run after major system updates to catch missing libraries.
Settings & Security Configuration
9 tips
Settings > Dashboard > General > Performance
Performance mode (master toggle), Disable glass effects, Disable glow effects, Reduce animations. Main optimization hub. Performance mode disables all visual effects at once for low-power hardware.
Settings > Dashboard > Desktop > Conky Control
Enable Conky now hides or restores the desktop monitor overlay immediately for the current session, while Start Conky on boot controls persistence. Disable the overlay to free 3-8% CPU. The Lite Dashboard diagnostics menu also includes Conky Mask Enable, Conky Mask Disable, and Conky Mask Status for privacy-safe screenshots.
Settings > Security > Credentials
Password, Two-Factor Auth (TOTP), Recovery Codes. Set up dashboard access protection. Generate and store recovery codes offline in case you lose your TOTP device.
Settings > Security > Auto-Lock
Lock after configurable inactivity period. Set to 1-5 minutes in shared or high-risk environments so the dashboard locks when you walk away.
Settings > Security > Failed Attempt Protection
Maximum failed login attempts and response action (lockout, block, shutdown, panic). Defines the escalation path, from temporary lockout to full panic response.
Settings > Security > Audit Log
Security event history: logins, lockouts, TOTP events, setting changes. Review who accessed the dashboard and when. Check for unexpected access attempts.
Global keyboard shortcuts with hold-to-trigger behavior. Arm from X11/XFCE desktop. Hold a key combination to trigger panic, kill-switch, or lockdown without opening the dashboard.
Sidebar Footer > Lock Button
One-click manual lock. Requires password (and TOTP if enabled) to unlock. Use before stepping away from the machine.
Scenarios & Power User Workflows
6 tips
Performance Optimization
Lowest resource usage: Open Sidebar footer > Settings > Dashboard > General > Performance and enable Performance mode. This disables glass blur, glow effects, and animations in one action.
Selective reduction: Leave Performance mode off and toggle only Disable glass effects and Reduce animations. Glass blur is the most GPU-expensive effect.
Desktop overhead: Open Settings > Dashboard > Desktop > Conky Control and disable Enable Conky now plus Start Conky on boot to cut 3-8% CPU. Also available from the Lite Dashboard or Kodachi Rofi Actions menu.
Quick animation kill: Click the clapperboard icon in the top status bar for instant toggle.
Scenario: Before Visiting a Sensitive Site
1. Open Sidebar > Overview > Actions and click Randomize MAC, Randomize Hostname, and Randomize Timezone to create a fresh identity. 2. Go to Sidebar > Essentials > Tor Essentials and rotate the exit node to a different country. 3. Open Sidebar > Command & Monitor > Command Builder > DNS Management (dns-leak) and run a leak test to confirm DNS goes through Tor. 4. Check Sidebar > Command & Monitor > Monitor > Network to verify no direct connections exist outside Tor/VPN. 5. Open the target site in Tor Browser (launched from the XFCE panel or the AutoShield wizard footer).
Scenario: Internet Connection Drops
1. Open Sidebar > Overview > Actions > Network Recovery and launch Fix Internet Wizard. 2. Read the pre-fix badges for Routing Status, DNS Configuration, DNSCrypt Status, Torrify Detection, IP Ping Check, Domain DNS Check, and HTTP Connectivity. If the host is torrified, trust HTTP more than ping. 3. Run the normal queue first: Full auto recovery, Flush DNS caches, Emergency fallback DNS, and Detect and fix DNS. 4. If that still fails, expand Advanced Steps and try Recover routing from failure, Toggle DNS mode, Restart DNSCrypt service, or Detorrify system when Tor firewall rules are the blocker. 5. Once the banner returns ONLINE, reconnect your preferred protocol from Essentials > Actions > Connection or fall back to VPNGate, then finish with a DNS Leak test.
Scenario: Switching from VPN to Tor
1. Open Sidebar > Command & Monitor > Command Builder > Routing and disconnect the active VPN protocol. 2. Switch to Sidebar > Command & Monitor > Command Builder > Tor Switch (DNS tab) and run torrify-system-nftables-dns to route all traffic through Tor. 3. Open Sidebar > Command & Monitor > Command Builder > IP Fetch to confirm the IP is a Tor exit node. 4. Run Sidebar > Command & Monitor > Command Builder > DNS Management (dns-leak) to verify DNS queries go through Tor. Note: Disconnect VPN before enabling torrification. To layer VPN + Tor, connect VPN first, then torrify.
Scenario: Emergency, Physical Access Threat
Fastest path: Use Emergency Shortcuts at Settings > Security > Emergency Protocol > Emergency Shortcuts. Hold the configured key combination to trigger panic without opening the dashboard.
From dashboard: Open Sidebar > Essentials > Emergency and use Kill Switch, which runs panic level medium (network blocked and every interface down, running processes terminated, memory caches and clipboard cleared, removable devices unmounted, screen locked), or trigger panic level (soft/medium/hard).
Duress: Enter the Duress Password at login to show a fake "System Update" while silently destroying data.
Power User: Command Queue & Favorites
Command Queue (Lite Classic): Drag commands from any service tab into the queue. Reorder via drag-and-drop. Execute sequentially or in parallel. Each command shows danger level badges.
Favorites: Star any command to save it. Access from the sidebar for one-click execution of frequent operations.
Output formats: Switch between Text, JSON, JSON-Pretty and JSON-Human in the output panel. JSON for structured data, JSON-Human for a readable summary.
Output Panel & Command Features
8 tips
Output Panel > Format Switching
Toggle between Text, JSON, JSON-Pretty, and JSON-Human formats. JSON-Pretty auto-validates and prettifies JSON output. JSON-Human converts technical output into readable summaries. Use Text for raw terminal output.
Output Panel > QR Code Rendering
When a command generates a QR code (e.g., VPN protocol configs, TOTP setup), the output panel renders it as an embedded PNG image. Scan directly from screen without saving to a file.
Output Panel > ANSI Color Support
Terminal color codes (ANSI escape sequences) are converted to HTML colors. Command output with colored status indicators, warnings, and highlights appears properly styled in the dashboard.
Output Panel > Copy & Clear
Click Copy to capture the full output to clipboard. Click Clear to reset the output between commands. The output auto-scrolls to the latest line during live command execution.
Command Builder > History Strip
The top of the command builder shows your recent command history. Click any previous command to re-run it instantly. Commands are tagged with danger level badges and auth requirement icons.
Command Builder > Dynamic Options
Each command exposes context-aware options in the builder. Toggle options on/off, set values, and preview the full command syntax before executing. Hover the info icon to see what each option does.
Command Builder > Danger Level Badges
Commands show color-coded danger badges: green (safe read-only), yellow (modifies system), red (destructive). Auth-required commands show a lock icon. Check these before running unfamiliar commands.
Queue > Drag-and-Drop Reorder
Drag queued commands to reorder execution sequence. Use the three-dot menu button on each item for Copy, Rerun, Requeue, Enable/Disable, Move Up/Down, or Remove. Disabling a command keeps it in the queue but skips it when you press Run All (the Run All button shows how many enabled commands will execute); you can still run a disabled command once from its Rerun menu. Expand each item to view its full output. Keyboard: Arrow keys navigate, Home/End jump to first or last, Enter runs or expands output, Delete removes, Ctrl+Shift+Arrow reorders, Ctrl+C copies, Ctrl+R reruns, Escape clears the selection.
Auto Runners & Background Tasks
5 tips
Settings > Dashboard > Runner > Auto Command Runner
Schedule any command to run at intervals from 10 seconds to 24 hours. Each task has its own interval, notification routing (dashboard, system, both, or silent), and enable/disable toggle. Tasks persist via systemd services, they keep running when the dashboard closes.
Auto Command Runner > Notification Enrichment
Enable metadata enrichment per task to include timestamp, CPU load, and RAM usage in notifications. System notifications auto-select icons based on command type (sudo, network, security, loop). View last execution time and exit code per task.
Settings > Dashboard > Network > Internet Health Check
Configurable background task that monitors internet connectivity and automatically runs health-control recover-internet when connection drops. Set check intervals from 10 seconds to 24 hours. Continues running when dashboard is closed. Toggle on/off without changing the interval.
Settings > Dashboard > Network > Command Timeouts
Two separate timeouts: Default Command Timeout (120s) for regular commands, and Network Command Timeout (180s) for VPN, Tor, and DNS operations that need more time. Settings sync automatically to the Rust backend.
Settings > Dashboard > Reset
Reset Layouts restores panel positions only. Reset All Settings performs a factory reset with detailed feedback showing what was cleared (runner tasks, GUI keys, etc.) and any warnings. Requires confirmation to prevent accidental resets.
AI Commander
7 tips
Essentials > AI Commander > Engine Selection
Choose from 10 AI engines: auto (smart routing), tfidf, onnx, onnx-classifier, mistral, genai, llm, and claude. Local engines (tfidf, onnx) work offline. Cloud engines (claude, genai) need internet. Use auto for best balance of speed and accuracy.
AI Commander > Voice Input
Use ai-cmd voice with device selection for hands-free command input. Enable --continuous mode for persistent voice sessions. The AI interprets voice commands and maps them to the correct Kodachi binary and flags.
AI Commander > Monitor Daemon
Background daemon that monitors your security score and generates actionable suggestions. Filter suggestions by category: security, privacy, network, performance. Resolve, dismiss, or cleanup suggestions. Set learning periods: last day, 7 days, 30 days, year, or all-time.
AI Commander > Scheduler
Schedule AI tasks to run at specific intervals. Add, list, and remove scheduled tasks. Combine with the Monitor Daemon for automated security posture management that runs continuously in the background.
AI Commander > Tor Proxy Support
Route AI queries through Tor using --tor-proxy for anonymous AI interactions. Cloud engine requests go through Tor circuits so your AI usage cannot be correlated with your identity.
AI Commander > Model Downloads
Download local LLM models in five sizes:
small (Qwen3-1.7B Q4_K_S, ~1.0 GB, fastest tiny model), default (Qwen3-1.7B Q4_K_M, ~1.1 GB, balanced for 4 GB RAM systems), large (Phi-3.5-mini, ~2.3 GB, 128K context for reasoning), xlarge (Qwen3-8B Q4_K_M, ~4.8 GB, 8B tuned for speed, needs 8+ GB RAM), and xlarge-hq (Qwen3-8B Q5_K_M, ~5.6 GB, 8B tuned for quality, needs 16+ GB RAM).
xlarge and xlarge-hq are the same 8-billion-parameter Qwen3 weights at different
quantization levels: pick xlarge for faster tokens/sec, xlarge-hq for closer-to-full-precision
output quality. Local models provide complete offline AI capability with no cloud dependency.
AI Commander > Discovery Reindex
Rebuild the AI service discovery index per binary. Run this after installing new binaries or updating services so the AI knows about all available commands and can accurately map natural language to the correct operations.
Monitoring, Network & Window Management
8 tips
Monitor > Terminal Tools Grid
Launch TUI tools in native terminal windows from the dashboard: htop, btop (system monitors), iftop, nethogs, nload (network monitors), ncdu (disk usage), plus DNS Config, Enabled Services, and APT Sources viewers. Each tool opens in its own terminal window, not inside the dashboard.
Monitor > Network > Local Ports & Routing
View all active listening ports with process names in the Local Ports panel. Inspect system routing tables in the Routing Table panel. Check current DNS resolver configuration in the DNS Config panel. Useful for verifying no unexpected connections exist.
Monitor > Resources > Machine Identity
View hardware identifiers and system fingerprint data in one place: CPU model, memory, kernel version, hostname, MAC address, disk info. Cross-reference with your randomization settings to confirm identity changes took effect.
Essentials > DNS Essentials > Database
Filter DNS servers by category: reputable, normal, encrypted, fallback and fetched. Search by name or IP, compare latency, and toggle between compact and grid views. DNSCrypt, Pi-hole and the DNS leak test sit on the same page.
Essentials > Tor Essentials > Instances
Create instances in batches, then start, stop, rotate and inspect each one. Weights for weighted load balancing live on the Load Balancing tab; exit countries, regions or alliances, per instance or for all, and the auto-IP-change timers live on the Routing tab.
Settings > Dashboard > Startup & Desktop
Appearance: Always on Top pins the dashboard above all windows. Startup: Auto-start on Boot launches the dashboard automatically; Start Minimized launches hidden in tray; Show Welcome Screen toggles the onboarding overlay. System Tray: Close to Tray minimizes instead of exiting; show/hide the tray icon independently.
Settings > Dashboard > Alerts
Set notification display duration (2-15 seconds). Enable command completion sound and admin message sound separately. Choose custom sound files for each event type. Preview sounds before saving to find the right alert level.
Notification Center
A bell in the sidebar opens the Notification Center, one place that unifies every alert source: admin messages, SOC findings, command queue results, the Auto Command Runner, hardening and emergency alerts, update availability, and device status. It is a dedicated page in Lite Classic and a modal in Circle. Each notification can be marked read, dismissed, snoozed (remind me later), or set to play a sound if it happens again; filter tabs split them by Admin, Security, System, and Queue. A settings panel chooses which severities are kept (All, Warning and above, or Critical only, with Critical always kept) and lets you mute categories from the unread badge. Dismissing an admin message also records the dismissal on the server so it stops being delivered to this device.
Sidebar > Collapse Sections & Version Check
The Overview, Essentials and Command & Monitor groups collapse independently. Collapsed state persists across sessions. The version number in the sidebar shows an update badge when a newer version exists. Click the version to see the detailed changelog and update details.
Mode Selection Guide
Circle is for first-time users and quick security checks, a gamified ring of 7 segments that restores down to 1400x1000. Lite Classic is the main dashboard: categorized pages, command queue and drag-and-drop, restoring down to 1400x980. Vitals and SOC (monitoring, no VPN, DNS, Tor or hardening controls) and ColonyOps (workflow and operator mode, 1030 mounted cells) complete the five; Vitals, SOC and ColonyOpsare Premium. Circle is the default; switch at any time from the Dashboards button on the left rail.
Discovery Without Memorization
If you do not know which binary provides a feature, open Sidebar > Command & Monitor > Command Library and search by keyword. The Library indexes all 606 commands registered under 26 CLI services and provided by 25 command-bearing binaries, with descriptions, danger levels, and required authentication status. This is faster than reading service documentation.
Hardening Checklist
For maximum security posture in under 60 seconds: open Sidebar > Essentials > Hardening > Features and enable what your threat model needs in the six groups (Internet Control, Hardware Devices, System Services, Security, Privacy, Performance). Then open Sidebar > Overview > Actions and run Randomize MAC, Randomize Hostname, and Randomize Timezone. Finish by verifying with Sidebar > Command & Monitor > Command Builder > DNS Management (dns-leak) and Sidebar > Command & Monitor > Monitor > Network.
AI Chat Across All Modes
The AI Chat button in the top status bar works in the Circle, Lite Classic and ColonyOps control cockpits. You can ask it to explain what a command does, suggest the right sequence for a task, or troubleshoot an error, all without leaving your current tab. For deeper AI control, use Sidebar > Essentials > AI Commander to access the AI Commander and configure AI daemons.
Browser Privacy Configuration
Kodachi treats browsers as high-risk attack surfaces and applies aggressive privacy hardening. Both ship with telemetry elimination, fingerprinting defense, and tracking protection at the configuration level. Neither is wrapped in Firejail by default; Tor Browser starts through Kodachi's hardened_malloc launcher when hardened_malloc is present, and you can start either one inside a Firejail profile yourself.
LibreWolf
Primary clearnet browser with 16 pre-installed privacy extensions
20+ testing links: IP detection (whatismyip, ipleak.net), DNS leaks (dnsleaktest.com), WebRTC leaks, fingerprinting (amiunique.org, EFF Panopticlick)
16Extensions
8Filter Lists
4Containers
20+Test Links
Tor Browser
Dedicated .onion access with three security levels
Three Security Modes
Standard: Full features. Safer: Disables JavaScript on non-HTTPS. Safest: Disables JS/fonts/media on all sites
Circuit Display
Transparent routing path visualization showing entry guard, middle relay, and exit node with country flags
Hardened Launcher
The kodachi-tor-browser launcher runs the browser through kodachi-hmalloc-exec when hardened_malloc is present and applies Kodachi's defaults from /etc/kodachi/torbrowser-defaults/user.js
.onion Service Access
Native support for onion addresses with automatic circuit creation for hidden services. No clearnet DNS lookups for .onion domains
Profile Separation
Dedicated browser profile prevents cross-contamination with LibreWolf. Separate cookie jars, cache, and browsing history
Circuit Refresh
New Identity button wipes all cookies/cache and creates fresh Tor circuits. Prevents long-term tracking correlation
3Security Modes
100%Onion Native
3Tor Hops
0Telemetry
Dual-Browser Architecture
Two browsers, two separate profiles. This dual-browser approach separates clearnet browsing (LibreWolf) from onion services (Tor Browser), preventing cross-contamination of browsing profiles and reducing fingerprinting surface area.
Separate ProfilesSeparate Cookie JarsSeparate Caches and History
Accessing .onion Addresses
.onion domains are special addresses that exist only within the Tor network. Regular DNS servers cannot resolve them, so browsers and applications need specific configuration to reach onion services. Kodachi provides two methods depending on your workflow.
Method 1: Tor Browser (Simplest)
Open Tor Browser from the XFCE panel or the AutoShield wizard footer. It handles .onion addresses natively with its own built-in Tor circuits. No system torrification is needed. Tor Browser manages its own SOCKS proxy and DNS resolution internally.
Zero ConfigurationNative .onion SupportOwn Tor CircuitsNo Torrification Required
Method 2: Kodachi Browser (LibreWolf) with Torrification
Stock LibreWolf blocks .onion domains (per RFC 7686); the Kodachi Browser profile already sets network.dns.blockDotOnion to false. To access onion services through Kodachi Browser, torrify the system, check the two settings below, and configure the FoxyProxy extension.
Step 1: Torrify the system with DNS redirection
Choose any of these methods:
Lite Dashboard
Open Sidebar > Essentials > Tor Essentials and click Torrify (send all traffic through Tor) on the Overview tab, or use Torrify System with its mode choice (single instance with DNS, or load balanced) on Sidebar > Essentials > Tools.
Command Builder
Open Sidebar > Command & Monitor > Command Builder > Tor Switch. The DNS tab runs torrify-system-nftables-dns (traffic and DNS through Tor), the Routing tab torrify-system-nftables, and the Load Balance tab torrify-system-nftables-load-balanced.
AutoShield
Open the AutoShield wizard tab from the dashboard header (shield icon). Enable the Torrify System + DNS step row, then click its play button.
Terminal
sudo tor-switch torrify-system-nftables-dns
Step 2: Open LibreWolf and navigate to about:config. Check these two values:
Open the FoxyProxy extension from the toolbar. Add a new SOCKS5 proxy entry and drag it to the top of the list so it takes priority. Set the proxy type to SOCKS5, the hostname to 127.0.0.1, and enable Proxy DNS (send DNS through the proxy). The port depends on your torrification mode:
Single Instance Torrify (torrify-system-nftables-dns)
Uses the default Tor instance. Set FoxyProxy to:
Type
SOCKS5
Hostname
127.0.0.1
Port
10000 (default instance SocksPort)
Proxy DNS
Enabled
Finding the correct ports for your instances
The port table below shows the default assignment. To verify the actual SOCKS, TransPort, and DNS ports for each running instance along with their current IP and exit country:
Lite Dashboard
Open Sidebar > Essentials > Tor Essentials > Instances. Instances are listed with their ports, IPs, and exit countries.
Command Builder
Open Sidebar > Command & Monitor > Command Builder > Tor Switch > Status and run list-instances-with-ip: it prints the SOCKS, control, DNS and TransPort ports, IP and exit of every instance.
Terminal
sudo -n tor-switch list-instances-with-ip
Tip: Always use nftables for torrification, as it is more reliable than iptables for transparent proxy and DNS redirection.
When using load-balanced torrification (round-robin, weighted, or consistent-hashing), Kodachi runs several Tor instances at once: the recommended count scales with RAM, at least 3 and at most 20 (about 150 MB each, see tor-switch recommended-instances). The table shows the first ten. Each instance can have a different exit country. Point FoxyProxy to the specific instance whose exit country you want for .onion browsing:
Instance
SOCKS Port
TransPort
DNSPort
kodachi_tor_inst_1
10000
14000
16000
kodachi_tor_inst_2
10001
14001
16001
kodachi_tor_inst_3
10002
14002
16002
kodachi_tor_inst_4
10003
14003
16003
kodachi_tor_inst_5
10004
14004
16004
kodachi_tor_inst_6
10005
14005
16005
kodachi_tor_inst_7
10006
14006
16006
kodachi_tor_inst_8
10007
14007
16007
kodachi_tor_inst_9
10008
14008
16008
kodachi_tor_inst_10
10009
14009
16009
Set exit country per instance, then point FoxyProxy to that instance's SOCKS port:
Lite Dashboard
Sidebar > Essentials > Tor Essentials > Routing > Exit Nodes: pick a country (e.g., Germany (DE)), region, alliance (e.g., 5-Eyes) or random preset, then Set exit country on all or Set on selected only.
Command Builder
Sidebar > Command & Monitor > Command Builder > Tor Switch > Exit Nodes builds the set-exit-node command for all instances or one instance.
Terminal
sudo tor-switch set-exit-node us --instance kodachi_tor_inst_1
Example: set inst_1 to exit via US, then use FoxyProxy SOCKS port 10000 to browse .onion through a US exit.
Load Balancing Modes
Round-Robin
Distributes traffic evenly across all active instances in sequence. Each new connection goes to the next instance.
Weighted
Distributes traffic proportionally based on configured weights. Higher-weight instances receive more traffic. Set weights with sudo tor-switch set-instance-weight kodachi_tor_inst_1 5
Consistent-Hashing
Routes traffic based on source IP hash (jhash ip saddr). On a single workstation all apps share one source IP, so they all hash to the same instance (effectively one stable exit IP). Note: TCP and DNS use different jhash seeds, so DNS queries may land on a different sibling instance than TCP flows.
How to set the mode and apply:
Lite Dashboard
Sidebar > Essentials > Tor Essentials > Load Balancing: select Round-Robin, Weighted (with weights) or Consistent Hashing, then torrify from the same tab.
Command Builder
Sidebar > Command & Monitor > Command Builder > Tor Switch > Load Balance: set-load-balancing-mode, per-instance weights, then torrify-system-nftables-load-balanced.
Terminal
sudo tor-switch set-load-balancing-mode round-robin then sudo tor-switch torrify-system-nftables-load-balanced
Why you see different exit IPs in the dashboard, the browser, and the widgets at the same time
Under load-balanced torrification, Kodachi runs several independent Tor instances in parallel (3 to 20, scaled to RAM). Each instance maintains its own circuit and its own exit relay, so each one ends up with a different exit IP in a (usually) different country. The nftables/iptables rules then spread outgoing TCP connections across those instances according to the selected mode.
The practical effect: every application and every TCP flow on the same machine can leave through a different Tor exit simultaneously. The dashboard IP widget may show one country (e.g. Norway), the browser may show another (e.g. Netherlands), and the integrity panel may show a third (e.g. France). All at the same moment, all genuine Tor exits, all correct. This is not a leak and not inconsistent state. It is the entire point of load-balanced multi-instance torrification.
Privacy benefit (per-flow IP isolation): because each new connection can land on a different exit, an observer correlating activity across services (e.g., site A and tracker B) sees connections coming from unrelated Tor exits. This breaks the simple "one user = one exit IP" linkability that single-instance torrification leaves in place.
Mode
nftables mechanism
Apparent exit IPs on this host
Best used for
Round-Robin
numgen inc mod N + conntrack stickiness: a stateful counter increments per new flow; existing flows stay pinned
Maximum diversity. Each new TCP connection lands on the next instance in sequence ⇒ different exit IP per new flow. Existing connections keep their original IP
General anonymous browsing, OSINT, scraping; anywhere request-to-request linkability is undesirable
Weighted
numgen random mod total_weight for TCP, jhash ip saddr for DNS: weighted RANDOM pick per new flow
Multiple exit IPs, weighted random. Each new connection picks an instance proportionally to its weight; over time, heavier instances absorb more flows but you still see several simultaneous exit IPs
When some instances have better latency, bandwidth, or a preferred exit country and should carry more traffic
Consistent-Hashing
jhash ip saddr mod N: mark = hash of the SOURCE IP. Same source IP ⇒ same instance, always
Effectively one stable exit IP on a single workstation. All local apps share one source IP, so they all hash to the same instance. Designed for gateway/router setups where multiple distinct clients (each with their own source IP) each get a stable assignment
Logged-in sessions (banking, captchas, anything that breaks when the IP changes mid-session), or multi-client gateways where each client needs session affinity
Quick decision guide:
Different IP per request, maximum unlinkability → Round-Robin. Pair with per-instance auto-IP-change timers (Command Builder > Tor Switch > Timers) so each instance also rotates its own circuit independently.
Different IPs, biased toward your best instances → Weighted. Set per-instance weights with sudo tor-switch set-instance-weight kodachi_tor_inst_1 5.
One stable IP across all apps on this machine, but still using the pool → Consistent-Hashing.
One stable IP and one shared circuit (no pool) → drop load balancing entirely; use sudo tor-switch torrify-system-nftables-dns (single-instance).
Note on conntrack stickiness: all three modes use ct mark set meta mark so that once a flow has been assigned to an instance, every subsequent packet in that flow stays on the same instance. The mode only decides where new flows go; long-lived TCP connections keep their original exit until they close or the underlying Tor circuit rotates.
Consistent-Hashing nuance: TCP and DNS use different jhash seeds. The generator emits two independent random seeds (tcp_seed for non-DNS TCP, dns_seed for DNS) so that the two traffic classes spread differently across the instance pool. This is a deliberate design choice for better distribution, not a bug. The practical effect on a single workstation: all TCP traffic pins to one instance (one stable TCP exit IP) AND all DNS traffic pins to one instance, but the TCP-side instance and the DNS-side instance can be different. Each is independently stable across time, so logged-in TCP sessions still see a stable exit IP; only DNS resolutions happen to leave through a (possibly different) sibling instance. If you must have TCP and DNS share the same exit, drop load balancing and use single-instance torrify (tor-switch torrify-system-nftables-dns).
Why this does not cause Tor-over-Tor
The nftables/iptables torrification rules exclude localhost (127.0.0.0/8) from the TransPort redirect. When FoxyProxy sends traffic to 127.0.0.1:10000, the connection stays local and reaches Tor's SOCKS port directly; it is not redirected through the TransPort a second time. The result is a single Tor layer, not double routing.
AI-Powered Intelligence
Kodachi Desktop integrates an AI operations suite whose supported remote requests can use configured VPN or Tor routes. Route choice changes the network path but does not guarantee anonymity or prevent an AI endpoint from receiving query and session metadata.
KAICS (Kodachi AI Command System) provides 8 specialized sub-binaries including ai-cmd for natural language OS control, ai-trainer for local model fine-tuning, and ai-gateway for routing selected AI requests through configured privacy routes. Supported requests can use Tor, but route choice does not guarantee anonymity or remove metadata sent to the AI endpoint.
Dashboard Fortress
The Kodachi Dashboard is locked behind a multi-layer authentication system. Password, TOTP two-factor, recovery codes, and automated threat response combine into a layered access-control system that blocks unauthorized dashboard access by default.
Password + TOTP 2FA
Primary authentication requires a strong password. Enable TOTP-based two-factor authentication for a second verification layer. Compatible with any authenticator app (Google Authenticator, Authy, etc.). With TOTP enabled, both factors are required on every login.
8 Single-Use Recovery Codes
When TOTP is enabled, the system generates 8 single-use recovery codes. Each code works exactly once. If you lose your authenticator device, these codes are your lifeline. Store them offline, printed, or in a separate encrypted volume.
Auto-Lock Timer
Configure automatic session lockout: 1 minute, 5 minutes, 15 minutes, 30 minutes, 1 hour, 4 hours, or never. When the timer expires, the dashboard locks and requires full re-authentication. Prevents walk-away exposure.
Audit Logging
Every authentication event is logged: successful logins, failed attempts, TOTP verifications, recovery code usage, lockouts, and configuration changes. A timestamped audit trail for review.
Threat Response Levels
When too many failed authentication attempts are detected, the system escalates through four configurable threat response levels. Each level applies progressively stronger countermeasures.
1
Temporary LockoutREVERSIBLE
Lock dashboard for configurable duration. User must wait before retrying. No data affected. Auto-unlocks after timeout.
2
Block Until RecoveryRECOVERY CODE
Lock dashboard indefinitely. Requires recovery code or system-level intervention to unlock.
3
System ShutdownPOWER CYCLE
Immediately powers off the machine. All volatile data in RAM is lost. Requires physical power-on to resume.
4
Trigger PanicSOFT, MEDIUM OR HARD
Runs the panic level you chose for this response. See Emergency Response for details.
Lockout → Block → Shutdown → Panic
SOC, Neural Monitor
The Security Operations Center (SOC) is one of the five cockpits, not a page inside another dashboard. It gives you a live neural map of host-security telemetry. Open it from the Dashboards button on the left rail, or pick it in the Quick Launch startup picker. SOC is a premium monitoring cockpit: it carries no VPN, DNS, Tor or hardening controls.
The Neural Map
The central canvas shows a security score core surrounded by ten color-coded cluster hubs. Each cluster represents a domain of host-security telemetry, and each domain's nodes light up to reflect current findings:
VITALS
CPU, memory, load, and core process health.
NETWORK
Interface state, active connections, and routing anomalies; splits into TCP, UDP, and Link sub-hubs when busy.
CONNECTIONS
Live socket table, listening ports, and unexpected outbound flows.
PROCESSES
Process inventory, privilege escalation indicators, and suspicious child processes.
THREATS
MITRE ATT&CK tagged findings, grouped into Trust, Rootkit, LAN, Persistence, Integrity and Hardening sub-hubs: critical-binary and file integrity, SUID/SGID drift, preload hijacks, boot-autoload changes, /dev anomaly, account integrity, and log-tamper.
AUTH
Failed logins, sudo events, and authentication anomalies from the system journals.
PRIVACY
Privacy posture summary: VPN, Tor, DNS encryption, and MAC randomization state.
SYSTEM
Kernel parameters, service integrity, hardening-module states, and CIS posture.
AGENTS
State of the Kodachi services and AI daemons reporting into the monitor.
LOGS
Journal and application log activity, including gaps and unexpected volume.
A cluster with many findings breaks into labelled sub-hubs (each with its own count and worst-severity color) so the map never crowds into an unreadable blob. The SOC is also hardening-aware: Kodachi's own protections, such as system-wide hardened_malloc and the tirdad kernel module, are reported as expected rather than as compromise.
Node color conveys severity at a glance: green = ok, teal = informational, yellow = warning, red = critical. Hover any node to expand its detail tooltip.
The WATCHER control arms continuous host-exposure monitoring: it enables and disables the kodachi-soc host-exposure systemd unit, which keeps listeners, inbound and outbound flows, shells, relays, forwarding and tunnels under eBPF observation instead of one-shot scans. A target that does not match an exact signed qualification stays visibly unsupported rather than silently uncovered.
While the dashboard is closed, the separately signed and unprivileged kodachi-soc-notifier user service reads only the bounded local summary and raises warning, critical, degraded, untrusted and unsupported alerts in your desktop session. It never scores or acknowledges a finding. The cockpit writes state in two ways, the WATCHER switch and acknowledging a finding, and every scan appends to the local score history. Reviewing, approving and revoking exposure policy is done on the command line with sudo kodachi-soc policy.
Additional Panels & Controls
Score Breakdown
Weighted per-cluster contribution to the overall 0-100 security score, updated on each refresh cycle.
Top Findings
Ranked list of the highest-severity findings across all clusters, with MITRE ATT&CK technique tags where applicable.
Privacy Posture
Compact summary of active privacy layers, VPN, Tor, DNS mode, and MAC randomization, drawn from live system state.
Live Alert Feed
Chronological stream of new findings as they arrive, colour-coded by severity. Scroll back to review recent history.
The toolbar provides: Pause / Resume to freeze the display, a configurable refresh interval, a severity filter to focus on warnings and above, per-cluster toggles to hide clusters you don't need, and an optional sound alert for new critical findings.
Monitoring cockpit. The SOC is a monitoring and visualization layer over Kodachi's existing security telemetry. It carries no VPN, DNS, Tor or hardening controls, though its WATCHER control arms and disarms the host-exposure unit. Use health-control commands or the dashboard action panels to act on findings.
WatchGuard & Monitoring
Continuous monitoring detects changes to your network identity, active interfaces, and running processes. WatchGuard runs as a background daemon that automatically blocks internet on detection and triggers alerts. Combined with Oniux process isolation, it monitors supported network and process events.
Watch Types
Watch Type
What It Monitors
On Detection
IP Change
External IP address shifts (VPN drop, Tor circuit change)
Auto-block internet via nftables/iptables/firewall/interfaces
Timezone Change
System timezone modifications (potential deanonymization)
Alert + optional auto-block
Interface Change
New network interfaces appearing (USB ethernet, rogue WiFi)
Auto-block + disable new interface
Process Monitor
Specific process lifecycle (e.g., Tor, VPN, DNS proxy)
Alert + auto-restart or auto-block
Tor Firewall Rules
Whether the Tor firewall you applied with Torrify is still in place, checked when the firewall changes and every 60 seconds (off by default; Kill Switch page card "Tor Firewall Rules")
Puts that Tor firewall back through tor-switch, at most 3 times a minute. Never blocks the network; does nothing after a detorrify, an internet block, a panic, nuke or a recovery, or after a reboot
Daemon Mode
WatchGuard runs as a persistent background daemon. Run it with sudo health-control daemon --config-id <ID> and check it with sudo health-control watch-guard status. Configurable polling intervals, automatic recovery attempts, and integration with the dashboard notification system. Beside IP, timezone, interface and process watches it also covers MAC, hostname, VPN and DNS changes.
Auto-Block Methods
When a watch triggers, internet is blocked with the configured method: nftables (drop all), iptables (reject all), UFW (deny all), bringing interfaces down, or all of them at once. WatchGuard then checks that traffic really stopped and, if it did not, retries with the other methods in turn.
System Monitoring (Lite Classic)
Extended monitoring covers: CPU/memory/disk resources, active network connections, running processes, firewall rule integrity, application logs, and startup service audit. Full-system visibility in one view.
Oniux Process Isolation
Oniux provides per-process Tor routing through Linux namespace isolation. Each isolated process gets its own mount namespace, user namespace, and network namespace. The process has no route to the real network except through Tor. Unlike proxychains or torsocks which rely on library preloading, Oniux uses kernel-level namespace isolation that an application cannot opt out of by skipping a preloaded library.
Mount Namespace
Isolated filesystem view. Process sees only the files it needs. Prevents reading system configuration or other users' data.
User Namespace
Unprivileged isolation. Process runs as a pseudo-root inside its namespace but has no real system privileges. Limits damage from exploitation.
Network Namespace
Dedicated network stack. Process can only reach the Tor SOCKS proxy. All DNS queries route through Tor. No direct internet access possible.
Audible Alert System
When WatchGuard detects a trigger event or a panic sequence activates, an audible alert sounds through the system speakers. Configurable alert sounds for different event types ensure you notice critical security events even when the screen is not visible. Sound player integration handles watchguard triggers and panic event notifications with distinct audio patterns.
Nuclear Options
When compromise is imminent or confirmed, Kodachi provides irreversible data destruction capabilities designed so that standard forensic recovery techniques cannot reconstruct the destroyed key material. Two independent nuke systems (LUKS Nuke at boot and the Dashboard Duress Protocol at the dashboard lock screen) keep data destruction one password away. Boot-time LUKS nuke works only on installs that keep the unlock prompt in initramfs, so if you require it you must install from the GRUB Debian-installer entry labeled Text + Full Disk Encryption, Boot-Nuke Compatible (or the unattended encrypted equivalent).
LUKS Nuke Password
Configure a special boot nuke password alongside your normal LUKS decryption password from the Dashboard Emergency > LUKS Nuke section. On a boot-nuke-compatible install, entering that password at the initramfs LUKS prompt triggers instant LUKS header destruction. On incompatible encrypted installs, the dashboard blocks boot-password configuration and tells you to reinstall through the GRUB Debian-installer encrypted path.
Header Overwrite
Overwrites LUKS header with random data, destroying all key slots
Key Slot Wipe
Individually destroys each LUKS key slot to prevent partial recovery
Sector Zeroing
Zeros the first sectors of the partition, eliminating filesystem signatures
GPG Backup
Before nuke configuration, automatically creates a GPG-encrypted backup of the LUKS header for authorized recovery, in Kodachi’s nuke backup folder; copy it off the encrypted disk if you want a way back, because the nuke password destroys that volume and the dashboard nuke and Destroy wipe the folder
Dashboard controls:Check Status, Set Password, and Remove Password manage the system-wide boot nuke password. The selected device is used for header backup and validation context. Execute Nuke is different: it immediately destroys only the selected LUKS device and remains available as a manual emergency action even when boot-time nuke is blocked on the current install.
Under duress, you hand over the nuke password. The system appears to attempt decryption, fails, and the key material is gone. What the adversary is left with is a partition that no password opens.
Dashboard Duress Protocol (Nuke Password)
Set a secret duress password in the dashboard. When entered at the dashboard lock screen instead of the real password, the dashboard shows a convincing "System Update" screen while destruction runs in the background. The person watching sees update progress bars and update text, and the feature writes no audit log entry of its own. Configure it under Settings > Security > Duress Password (Nuke): it needs your master password, a nuke password of at least 12 characters, and a wipe method (fast, secure or paranoid).
Fake Update Screen: Displays 13 simulated update phases (downloading, verifying signatures, installing libraries and so on) with progress percentages and completion messages, designed to read as a routine system update. If destruction takes longer, extra phases keep the screen moving until it finishes.
Destroy Kodachi, Sidebar Icon
A red Destroy Kodachi icon (skull) is the last icon at the bottom of the left rail that every cockpit shares. It can be shown or hidden from Settings › Security. Clicking it opens an in-window confirmation (configurable in Settings), then runs a combined, two-stage emergency destruction sequence in order:
1LUKS Header Wipe: Wipes every LUKS device on internal and boot media, unlocked or locked, and Kodachi's own header backups (removable drives only if you opted in), before any further action runs. No password opens a wiped device again; only a header backup kept outside Kodachi's own backup folder could restore one.
2Hard panic: Kills the network, clears the clipboard and memory caches, unmounts devices, forces the power off, then starts 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. Stage 1 also wipes the header backups the LUKS nuke saved, and removable USB drives are included only when you turn that on in Settings.
Configurable confirmation: The confirmation style is set per-dashboard in Settings. Three modes are available: type DESTROY (default), a simple Yes/No prompt, or immediate with no confirmation. Destruction starts immediately once confirmed, and every notice it shows while it runs reads as a routine system update, never as a wipe.
IRREVERSIBLE: Once triggered, this action cannot be stopped or undone. The LUKS header wipe alone makes the encrypted data unreadable to any password.
This is one of three independent destruction paths in Kodachi. The other two are: emergency global keyboard shortcuts via the kodachi-session-helper daemon (configured in Settings > Security > Emergency Shortcuts), and the LUKS Nuke on the Emergency page (plus the boot-time nuke/duress password set at the LUKS prompt). See Global Emergency Shortcuts and the LUKS Nuke card above for those paths.
Nuke Execution Paths
Dashboard Native - 9 Phases
1Network Kill: Block all outbound traffic first, so nothing can be exfiltrated while the rest runs
2LUKS Header Wipe: Destroy the headers of encrypted partitions so no password opens them, and it runs in every mode
3Memory and Swap: Turn swap off and clear memory caches before the parallel stage starts
4-7Parallel Destruction: Crypto keys and sensitive config, browser data, user data, and system logs (concurrent), then the broader directory sweep
8Boot Destruction: Destroy the boot partition, MBR and EFI so the system cannot boot again
9Shutdown: Force power off, the system stays off
The nuke password and a one-time token are validated before phase 1 begins. Execution goes through a privileged helper binary, and falls back to individual phase execution if that helper is unavailable.
Health-Control CLI - 14 Phases
1Network Kill: Kill all network connectivity first, before anything is touched
2LUKS Header Wipe: Overwrite the headers of encrypted devices and Kodachi's own header backups, so no password opens them
3Swap and Memory: Clear swap and memory before the parallel stage
4-10Parallel Wipe: SSH and GPG secrets, crypto wallets, browsers, messaging apps, email clients, user data directories, credentials and configs (concurrent)
11History and Logs: Shell history and system logs, run last so anything written during the wipe is caught
12Temp Files: Temporary and cache directories
13Boot, EFI, MBR and GPT: Destroy the boot chain so the system cannot boot again, in every mode
14Shutdown: Force power off, the system stays off
Full standalone destruction with storage-aware wiping. Detects SSD, NVMe, and HDD for optimal destruction method.
Global Emergency Shortcuts (Session-Wide)
The kodachi-session-helper daemon runs as a user-session service and provides session-global keyboard shortcuts for emergency actions. Unlike dashboard shortcuts, these work even after the dashboard window is closed, anywhere in the X11 session.
Hold-to-Trigger
A shortcut is a modifier combination plus a trigger key held 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. The minimum number of modifiers depends on the action: three for the LUKS header wipe and the combined nuke, two for the dashboard nuke, one for delayed lockdown. Auto-repeat is rejected, so a stuck key cannot fire it.
Hardware Corroboration
X11 key grabs are verified against raw /dev/input events inside a correlation window (2 seconds by default), so synthetic input (XTEST) cannot trigger emergency actions. On a VM whose virtual keyboard never reaches /dev/input you can switch this check off, and then synthetic keystrokes can fire shortcuts.
Offline Operation
No network or authentication server required. Uses local session tokens. Emergency actions work even when completely offline.
Delayed Lockdown
Schedule timed lockdown (1m to 24h). Countdown persists across restarts. Cancel with authenticated session token before expiry.
X11 Session Only: Global shortcuts require an X11/XFCE session. Wayland sessions are detected and fail closed. Configure shortcuts from the Dashboard Settings > Security > Emergency Shortcuts panel.
Wipe Intensity Comparison
Mode
Passes
Standard
Use Case
Fast
1 random pass + zero
Single overwrite
Quick destruction when time is critical
Secure
3 random passes + zero
Not the DoD 5220.22-M sequence
Standard secure wipe, the default
Paranoid
7 random passes + zero
Extended overwrite
Maximum destruction for highest threat scenarios
The passes above are for a hard disk. On an SSD or NVMe root, personal folders are deleted without overwriting. Every method also destroys the boot sector, GRUB, kernels, initrd and MBR, so the system will not boot.
Storage-Aware Wiping
SSD
blkdiscard --secure: TRIM-based secure erase triggers the drive's built-in secure wipe, falling back to a plain discard on drives without secure discard.
NVMe
nvme format -s 1: the NVMe User Data Erase format, carried out by the drive itself across the namespace.
HDD
shred multi-pass: Traditional multi-pass overwriting with random data patterns. Necessary for magnetic media where TRIM is not available.
Emergency Response
Three escalation levels of panic mode take you from a recoverable lockdown to an immediate power-off; none of them deletes files on disk. Irreversible destruction is the separate Destroy Kodachi and nuke path above. The network step sets the IPv4 firewall to drop everything, stops NetworkManager, Tor and OpenVPN and takes every interface except loopback down, all at once.
Panic Soft
Recoverable. Defensive lockdown without data loss. Runs at once, no confirmation.
Kill all network connections
Clear the clipboard
Lock the screen
Recovery: panic-recover restores the firewall rules, network services and interfaces recorded before the cut
Panic Medium
Network recoverable. Asks for confirmation first.
Everything in Panic Soft, plus:
Terminate non-essential processes
Clear memory caches
Unmount external devices
Recovery: panic-recover restores the network it recorded; ended processes and unmounted devices do not come back
Panic Hard
Immediate power-off. Asks for confirmation first.
Everything in Panic Medium except the screen lock, plus:
Force the power off
Then 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.
Recovery: boot again. Disks are untouched; whatever was only in RAM is gone.
Drop all traffic via nftables ruleset (preferred on modern systems)
block-internet --method iptables
iptables
Drop all traffic via iptables rules (legacy fallback)
block-internet --method firewall
UFW
Reject all traffic via UFW (also accepted as --method ufw)
block-internet --method interfaces
Interface down
Bring down all network interfaces (physical disconnection)
block-internet --method all
All methods
Apply all four methods at once; with no --method the command uses auto and picks the methods available on the system
kill-network
Combined
Kill all network processes, connections, and interfaces
kill-network-interface --interface <iface>
Targeted interface kill
Disable a specific network interface (for example: wlan0) without affecting others
Recovery Commands
After Panic Soft, Panic Medium or a triggered kill switch (which runs Panic Medium), run sudo health-control panic-recover: it restores the firewall rules, network services and interfaces recorded before the cut, and the Recover button on the Emergency page runs the same command. unblock-internet does not undo a panic: it only reverses its own Block Internet, so after a panic it finds nothing of its own to undo and changes nothing. The broader recover-internet attempts 10 recovery methods automatically: 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. Falls back through each method until connectivity is restored.
Identity Randomization
The main identifying attributes of your system can be randomized on demand. MAC address, hostname, timezone and IPv6 settings together make your machine look like a different device from one session to the next.
Before
MAC00:1A:2B:3C:4D:5E
Hostnamekodachi-desktop
TimezoneAmerica/New_York
IPv62001:db8::1
→
After
MACF2:7C:9A:11:B8:03
HostnameDESKTOP-K4N92TX
TimezoneAsia/Tokyo
IPv6Disabled
MAC Address Control
sudo health-control mac-change-all: Randomize all interfaces
sudo health-control mac-force-change: Force the change by taking interfaces down first
sudo health-control mac-change-specific: Target one interface
sudo health-control mac-reset-all: Restore the original hardware MACs
sudo health-control mac-show-macs: Display the current MAC addresses
Hostname Randomization
9 categories of hostnames that look like real machines (health-control list-hostnames --category <name>):
Linux: Ubuntu-Desktop, Ubuntu-Server-22.04 and other distributions
Apple: MacBook-Pro, iMac patterns
Network: office server names such as NYC-FS01
Business: HQ-Reception-01, Conference-Room-A
Gaming: gaming PC names
Mobile, IoT and Fiction: phones, Raspberry Pi style devices and fictional names, chosen only on request
A plain random hostname draws from the categories that are plausible on a laptop or desktop and leaves Mobile, IoT and Fiction out.
Timezone Management
Random, regional, or matched to your exit:
IP-based sync: sudo health-control sync-timezone matches the timezone to your public IP's location (your VPN or Tor exit when one is active)
Random: sudo health-control set-random-timezone picks any installed zone
Africa / Americas / Asia / Europe / Australia / Pacific / UTC: region-specific random selection with --category
IPv6 Control
IPv6 leaks your real identity through link-local addresses and SLAAC. Kodachi provides full IPv6 management with the Dashboard as the single source of truth:
Every live boot entry: IPv6 disabled at kernel level (ipv6.disable=1), so the stack is never initialized and the Dashboard cannot re-enable it. This is not tier-dependent; there is no live entry that leaves IPv6 runtime-toggleable
Installed systems: the Kodachi security-mode entries carry the same flag; the stock Kodachi OS GNU/Linux entry does not, and that is where the runtime toggle applies
sudo health-control ipv6-enable: reverses all of the above; warns when the kernel was booted with ipv6.disable=1, which only a reboot into an entry without that flag can undo
Installed systems: persistent state lives in /etc/default/grub.d/50_kodachi_ipv6.cfg and survives reboots after update-grub
Data Destruction Arsenal
Beyond the nuke sequences, Kodachi provides granular control over data destruction. Wipe specific categories, target individual applications, overwrite free RAM to limit cold boot attacks, or create encrypted containers for sensitive data isolation.
Wipe Standards
DoD 5220.22-M
3
passes. US Department of Defense standard. Overwrite with zeros, ones, then random data.
Gutmann (Simplified)
9
passes. Simplified Gutmann method targeting modern drive architectures.
RCMP TSSIT OPS-II
7
passes. Royal Canadian Mounted Police standard. Alternating overwrite patterns.
Wipe Target Categories
Browsers
LibreWolf, Firefox, Tor Browser, Chromium, Brave, Chrome, Vivaldi, Opera: history, cookies, cache, saved passwords, form data, downloads
Signal, Session, Element, Telegram, Discord, Slack and Pidgin, plus the Thunderbird, Evolution, Geary and Claws Mail email clients: message databases, contact lists, media files
Free space overwrite, swap partition wipe, temp directories, user cache, thumbnail cache
RAM Wipe & Cold Boot Defense
4 Wipe Policies
Choose the RAM wipe engine:
kodachi-wiper: Custom Kodachi memory wiper
sdmem: Secure-delete memory wiper
both: Run both engines sequentially
auto: Runs kodachi-wiper
Automatic on Shutdown
Opt in once: install the shutdown hook with sudo health-control wipe-ram-install, then turn it on with sudo health-control ram-wipe-enable (or the RAM Wipe on Shutdown control in AutoShield). From then on free memory is overwritten when the system powers off or reboots, within the time budget; a fresh ISO ships with it off. This limits what a cold boot attack, where an adversary freezes RAM chips to extract encryption keys, can recover.
Encrypted Containers
Create on-demand LUKS encrypted containers for sensitive data isolation:
container-create: Create new encrypted volume
container-mount: Mount with passphrase
container-unmount: Securely unmount
USB & Hardware Security
Physical hardware ports are attack vectors. Kodachi implements a 4-layer USB defense system combined with hardware device controls to shut down physical attack surfaces that software-only solutions miss.
4-Layer USB Defense
Layer 1: USBGuard Policies
Rule-based device authorization. Whitelist known devices, block unknown USB by default. Policy-driven access control for every USB port.
Layer 2: Kernel Modules
Blacklist USB storage kernel modules (usb-storage, uas). Prevents the kernel from recognizing USB mass storage devices entirely.
Layer 3: Device Authorization
Sysfs-level authorization control. Set authorized attribute to 0 for individual USB devices, preventing driver binding at the bus level.
Layer 4: Blacklist Rules
Modprobe blacklist configuration for specific device classes. Block entire categories of USB devices (HID, audio, video) via persistent rules.
Hardware Device Controls
Device
Disable Method
Why It Matters
Webcam
Kernel module blacklist (uvcvideo)
Prevents remote camera activation by malware or exploits
Microphone
ALSA capture and every desktop-session source muted, with a guard that keeps them muted
Blocks audio surveillance and room monitoring
Bluetooth
rfkill block + kernel module blacklist
Eliminates Bluetooth tracking, pairing attacks, and BLE beacons
WiFi
NetworkManager radio off + rfkill block
Prevents WiFi probe requests that reveal device identity
Hardware RNG Verification
sudo health-control hardware-rng-verify runs the FIPS 140-2 rngtest battery on /dev/hwrng, or on /dev/random when the machine has no hardware RNG device, and reports the result. It flags a failing generator; no test can prove a generator is uncompromised. Critical for cryptographic key generation.
Entropy Pool Monitoring
Monitor /proc/sys/kernel/random/entropy_avail in real-time. Low entropy starves cryptographic operations. sudo health-control entropy-status reports the pool and the hardware RNG backend, and advises when that backend should be fed through rngd.
Boot Integrity Checking
sudo health-control boot-integrity-check reports the boot chain on demand: UEFI mode, Secure Boot and MOK state, shim and GRUB configuration, and kernel lockdown, with recommendations for what is weak. It inspects configuration; it does not keep a hash baseline of the boot partition.
Debug Collector
If you encounter issues with your Kodachi Desktop installation, the Debug Collector gathers system diagnostics into a single zip file you can share with me. It collects boot logs, hardware specs, network configuration, Kodachi service status, and more.
Privacy First
The 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 before collection starts.
Run the debug collector (interactive category menu):
The output zip is saved to your Desktop (~/Desktop/kodachi-debug-*.zip). Upload it to your preferred file-sharing service and share the link with me on Discord or via the contact form.
Binary Security Suite
Kodachi Desktop ships a full set of high-performance binaries that form a unified security control plane. The binaries are written to a strict error-handling policy that returns failures as errors instead of crashing.
health-control
255 commands: System monitoring, a read-only system doctor and boot-readiness check, emergency panic modes, security scoring, kill switches with a Tor firewall watch, MAC randomization, hostname management, firmware and platform security checks, and memory security controls.
tor-switch
127 commands: Tor lifecycle management, load balancing, exit node control, system-wide torrification, circuit management with a live relay view, hosted onion services, and bridge transports.
dns-switch
45 commands: DNS server management, DNSCrypt configuration, Pi-hole integration, and encrypted resolution enforcement.
routing-switch
31 commands: VPN and Tor routing control, protocol switching between 14 transport protocols, and traffic redirection rules.
integrity-check
Binary signature verification, cryptographic hash validation, and system file integrity monitoring against the signed baseline.
permission-guard
File permission monitoring and enforcement. Detects unauthorized permission and ownership changes across critical system paths; scan reports them, and scan --fix or watch with auto-fix restores them.
All binaries log through logs-hook, one log per binary with timestamps and levels, so a session can be reconstructed for forensic analysis. The kodachi-dashboard exposes the entire suite through a unified GUI.
Pre-Installed Kodachi Binaries
Kodachi bundles 29 binaries pre-installed at /opt/kodachi/dashboard/hooks/ (the 21 core binaries below plus the 8-binary KAICS AI suite). Launch the complete security toolkit instantly without additional setup.
Kodachi Desktop ships a curated selection of GUI applications organized by dynamic layers. Always-on applications are loaded at every boot; optional layers can be activated on demand.
Timeshift, Synaptic, CoreCtrl, Qalculate, wavemon, LinSSID, Font Manager, MenuLibre
External Packages (installed via hooks)
Preinstalled in the ISO: LibreWolf, Tor Browser, Monero GUI, VeraCrypt, Portmaster, Mission Center
From the Repository Manager: VSCodium, GitKraken, Session Desktop, Cwtch, Tabby, Obsidian, Joplin, Termius, ExifCleaner and WaveTerm come from the Kodachi apt repository's apps component (the exact upstream packages), and Debian software such as VLC, Bluefish and the QEMU / Virt Manager set installs the same way.
Cwtch is a metadata-resistant messenger: there is no Cwtch service or Cwtch network, and all communication is end-to-end encrypted and takes place over Tor v3 onion services. Its cell in the dock's Net Tools group opens Cwtch when it is installed, and the Repository Manager when it is not.
Dynamic Layer System
Kodachi Desktop uses a modular layer system that groups the desktop by purpose. Every layer's applications ship installed in the ISO; a layer that runs background services (network, printing, VM guest and VM host) is switched on or off by the layer manager, so services you do not need never start.
Layer Activation Map
Layer
Name
Activation
Approximate Size
02
XFCE Desktop
Always loaded (core desktop)
~400MB
03
Network GUI
Normal boot or "Enable Browser" button
~300MB
04
Multimedia
"Enable Multimedia" button
~450MB
05
Office
"Enable Office Suite" button
~800MB
06
Printing
"Enable Printing" button
~200MB
07A
VM Guest
Auto-detect (VMware only)
~20MB
07B
VM Host
Installed on demand from the Kodachi Repository Manager, Additional apps entry "QEMU and Virt Manager" (not shipped in the ISO)
~400MB once installed
08
Security GUI
"Enable Security Tools" button
~280MB
09
Development
"Enable Development" button
~350MB
11
Utilities
"Enable Extra Utilities" button
~120MB
Boot Modes
Normal boot: Layers 02 + 03 auto-loaded (desktop + browsers/network)
Minimal boot: add the kodachi.mode=minimal kernel parameter (there is no menu entry for it): the core desktop starts, optional services such as Tor, Bluetooth and Syncthing stay off, and CUPS and Avahi are masked
VM detected: Layer 07A (VMware guest tools) auto-enabled when running inside a VM
Not bundled in the ISO. virt-manager, qemu-system-x86, libvirt-daemon-system and the rest of the QEMU set are installed from the Kodachi Repository Manager, Additional apps entry "QEMU and Virt Manager"
All terminal.list.chroot packages (networking, VPN, security, firmware, tshark)
AI & Intelligence
Optional
KAICS tools (ai-cmd, ai-gateway, and related binaries)
Supported Routing Protocols
Kodachi Desktop ships with 14 scored routing protocols via the routing-switch binary, covering everything from battle-tested VPNs to advanced censorship-resistant transports. Plain routing-switch auto-select ranks 12 of them: AmneziaWG and OpenVPN over Cloak are opt-in and only enter the ranking with --prefer-obfuscated, and xray-vmess is a legacy factory fallback.
Routing Protocol Coverage
Category
Protocols & Features
VPN Protocols
OpenVPN (industry-standard, AES encryption), WireGuard (modern, ChaCha20 encryption) with kill switch and DNS leak protection
Censorship-Resistant VPN
AmneziaWG (WireGuard with the handshake disguised, same ChaCha20-Poly1305 crypto and UDP data path, interface awg0), OpenVPN over Cloak (OpenVPN wrapped in the cbeuw/Cloak pluggable TCP transport, so the outer connection looks like an ordinary browser HTTPS session to a real decoy site). Pick these only when a network blocks VPNs by protocol signature.
SOCKS5 (standard proxy), Dante (SOCKS5 route through a Kodachi node), Microsocks (a local SOCKS5 server that shares the active tunnel with other devices on your LAN)
Tor Integration
Redsocks (transparent Tor routing), SOCKS proxy configuration, TransPort routing, DNS over Tor, System-wide torrification (can run on top of a running VPN connection). The remote Tor route is VPN-only: connect WireGuard or OpenVPN first, then it layers Tor on that tunnel. The worker Tor SOCKS port is never exposed on a public IP (an open Tor SOCKS proxy gets abused), so it is reachable only from inside the Kodachi VPN network.
Multi-Layer
VPN + Tor (double encryption), protocol chaining for enhanced anonymity, traffic obfuscation layers
AmneziaWG is WireGuard with the handshake disguised. A stock WireGuard handshake is a fixed 148-byte initiation packet that deep packet inspection fingerprints trivially. AmneziaWG sends junk packets first and randomizes the header fields, so that signature is gone. It keeps WireGuard's ChaCha20-Poly1305 crypto and its UDP data path, so steady-state speed is essentially WireGuard's. The interface is awg0 and not wg0, so wg show reports nothing while the tunnel is up and perfectly healthy. Use awg show instead. It requires the amneziawg kernel module, and it is not interoperable with a stock WireGuard peer in either direction. On mobile, only the official AmneziaVPN app can connect. A normal WireGuard app cannot.
OpenVPN over Cloak wraps OpenVPN in the cbeuw/Cloak pluggable TCP transport. The outer connection looks like an ordinary browser HTTPS session to a real decoy site, and anything probing that port without a valid Cloak key is served the decoy instead of a VPN handshake. A separate ck-client process holds the real TCP connection, and the OpenVPN config deliberately points at 127.0.0.1, so any address or port you read out of the .ovpn text is the loopback one and not the real endpoint. The cost is TCP inside TCP, which degrades non-linearly once a link starts losing packets. No measured throughput figure has been published. In practice it is desktop-only, because mainstream mobile OpenVPN apps cannot launch the separate Cloak transport process.
When These Two Are the Wrong Choice
Both solve exactly one problem: a network that identifies and blocks VPN protocols by signature. On any network that is not doing that, both are strictly worse than the plain parent protocol, since you pay the obfuscation cost and gain nothing. Neither is a substitute for Tor either. They hide what protocol you are speaking from the local network, they do not hide who you are from the endpoint.
Escalation order: start with plain WireGuard or OpenVPN. If the tunnel fails the same way every time on one specific network while the same credentials work elsewhere, that is protocol blocking, so try AmneziaWG next, because it keeps WireGuard's speed. If UDP itself is blocked rather than merely fingerprinted, AmneziaWG cannot help you, because it is still UDP. That is the case where OpenVPN over Cloak is the answer.
Where You Pick Them in the Dashboard
In the Kodachi Dashboard both protocols appear wherever WireGuard and OpenVPN already do: the Essentials > Actions > Connection block and its quick actions, the AutoShield Connect WireGuard chevron menu, the routing wizard, and the authentication card. AutoShield's VPN connect step offers both as options, and its default is still WireGuard, so nothing changes for you unless you choose one of them. If your account card was generated before these protocols existed it simply carries no entry for them, and the dashboard treats a missing entry as protocol unavailable rather than as an error.
Torrification Capability
Kodachi Desktop supports system-wide torrification that can run on top of a running VPN connection. Layer Tor routing on top of WireGuard, OpenVPN, Hysteria2, Shadowsocks, V2Ray, or Xray connections for enhanced anonymity. Use sudo tor-switch torrify-system-nftables-dns to torrify your entire system regardless of your underlying VPN connection.
Security Over Raw Speed
Kodachi hardens all supported routing protocols as much as possible, not just WireGuard and OpenVPN, so some connections may benchmark slower than vendors that optimize mainly for raw throughput.
That tradeoff is intentional: leak resistance, kill switch enforcement, DNS protection, stricter routing defaults, and privacy-focused safeguards take priority over maximum speed.
If you prefer a different balance, boot a less restrictive mode or use another provider. Kodachi includes access to alternatives such as RiseupVPN and VPN Gate, and you can also use other commercial or free providers if you prefer.
Security & Privacy Features
Kodachi Desktop inherits the full terminal security stack and adds GUI-specific protections for desktop environments.
Live session: passwordless sudo. Installed system: the sudo group runs the Kodachi binaries and dock actions without a password; anything else asks for it
Conky Desktop Monitor
Live Security Telemetry Rendered on Desktop
Lua-powered desktop monitor with 5 panels plus an optional logo, 27 monitoring scripts, 8 Cairo gauges, and a shared Rust conky-status gateway so the desktop always shows identity, routing, and system health at a glance.
Signal Deck
The top-center deck is event-driven. It stays quiet when the system is stable, then surfaces changed identity, routing, security, and system values first so anomalies are obvious immediately.
Shared Telemetry Path
All panels consume the same cached snapshot instead of rerunning expensive checks. Rendered values are escaped before drawing, and returned text is not executed as shell input in the display path.
Low-Overhead Mode
Open Settings > Dashboard > Desktop > Conky Control and turn off Enable Conky now to hide the desktop overlay for the current session, or use Conky Disable on Lite Classic's Actions page (Desktop & Display) when you want the lowest CPU use on older or low-power hardware.
Privacy Screenshot Mode
Lite Classic's Actions page (Desktop & Display) includes Conky Mask Enable, Conky Mask Disable, and Conky Mask Status. These commands mask sensitive fields such as IP, MAC, and country data in the Conky panels for safe screenshots, then restore real values when unmasked.
Always-On Visibility
The desktop overlay keeps high-signal CPU, memory, network, VPN, Tor, and security posture information visible without opening the dashboard first.
5Panels
27Scripts
8Cairo Gauges
7Config Files
Gauges + Resources
280px gauges · 265px resources
Upload Ring: Orange, tx rate
Download Ring: Pink, rx rate
CPU Ring: Cyan, core average
Memory Ring: Green, used/total
Disk Ring: Purple, root partition
Swap Ring: Yellow, swap usage
Ping Ring: Red dual-ring, domain ping outside and DNS ping inside
Bandwidth Ring: White, combined throughput
Resources panel: CPU and memory with the top three processes for each, buffers and cache, swap, root and EFI disk use, CPU frequency and load
Security Status
265px × Full Height
Privacy status: internet state, login, active route, public IP with ping, country and city, account group, block state, session and security IDs
Anonymity: Tor and Tor DNS, Tor exit IP and country, torrify state and backend, DNSCrypt, Kodachi Net, Tor and VPN connection age
Security: USBGuard, USBKill, the security score out of 100 and the hardening level
System status: nuke state, auto-login, disk and swap encryption, active swaps
Network: active interface, gateway, MAC address and whether it is randomized, interfaces
System + Traffic
265px × Full Height
System: files, threads and processes, uptime, timezone, host and NTP, time and date, workspace, resolution, kernel, boot mode
Account card: your Kodachi VPS card details and nodes, shown only when a card is present
Versions: binary pack, Terminal and Desktop: a green dot means yours is current or newer, red means a newer release is published
AI agents: detects more than 40 local AI agents and model servers, such as Claude CLI, Codex CLI, Gemini CLI, Ollama, llama.cpp, LM Studio, Aider, Open Interpreter, Copilot CLI and cursor-agent, with CPU and memory per agent
Crypto and metals: BTC, ETH, XMR, AZERO, gold and silver; off until you enable prices in the Dashboard
Traffic: card traffic, upload and download rates and totals, local IP
Logo (optional)
220px wide
Kodachi logo: a small overlay the launcher starts only when the logo is enabled
Advanced Monitoring Features
Staggered Refresh: panels refresh on offset intervals (7, 11, 13, 17, 31, 37, 61 and 113 seconds among them) so their checks rarely fire together
VPS Node Status: each Kodachi node on your account card with its status, country and whether its Tor exit is visible
Crypto Prices: BTC, ETH, XMR, AZERO, gold and silver, off until you enable them in the Dashboard
Version Alerts: a red dot beside the binary pack, Terminal or Desktop row when a newer release is published
Lock Files: slow refreshes such as the Signal Deck news take a lock, so they never run twice at once
Privacy Ping: rotates through Cloudflare, Quad9 and OpenDNS resolvers and privacy domains such as mullvad.net and duckduckgo.com (zero Google)
Systemd Watchdog: checks the panels every 5 seconds and restarts them after two checks in a row find one missing, duplicated or misplaced
Shared Snapshot: one conky-status snapshot, refreshed by a systemd timer, feeds every panel
Rofi Menu System
Kodachi Desktop ships a pre-configured Rofi menu system with 202 theme and configuration files covering application launchers, power menus, system applets, and color schemes. Combined with the Kodachi Rofi Actions menu scripts, this provides keyboard-driven access to security operations, network controls, and system utilities without touching the mouse.
Rofi Configuration Overview
Component
Count
Description
Launcher Themes
7 types
Application launcher styles ranging from minimal search bars to full-screen grid layouts, each with shared color/font configuration
Power Menus
6 types
Shutdown, reboot, lock, suspend, and logout dialogs with confirmation prompts and themed layouts
Applets
5 types
Quick-access system applets (brightness, volume, screenshot, network, battery) with multiple visual styles
Color Schemes
16 palettes
Pre-built .rasi color themes that apply across all launcher, power menu, and applet types
Theme Files
162 .rasi
Complete Rofi theme definitions covering layout, typography, colors, and element spacing
Scripts
23 .sh
Launcher and power menu runner scripts that invoke Rofi with the correct theme, mode, and arguments
Images
16 assets
Background images and icons used by themed launcher and power menu layouts
Primary dispatcher: launches sub-menus for favorites, network, services, and utilities
Favorites
menu-favorites.sh
Quick-launch frequently used security tools and applications
Network
menu-network.sh
VPN connect/disconnect, Tor toggle, DNS switching, routing mode selection
Services
menu-services.sh
Start, stop, and check status of system services (Tor, DNSCrypt, firewall)
Utilities
menu-utilities.sh
System cleanup, MAC randomization, hostname change, panic triggers
All Rofi menu scripts are installed to /usr/local/lib/kodachi-rofi/ and invoked via the kodachi-rofi-actions launcher. Theme and configuration files live in ~/.config/rofi/ and are automatically deployed to new user accounts through the /etc/skel skeleton directory.
Desktop Customization
Kodachi Desktop ships with a carefully crafted dark theme optimized for long coding and privacy sessions.
Theme Configuration
Component
Configuration
GTK Theme
LK_Material-Black-Lime (dark theme with lime green accents)
Icon Theme
Newaita-reborn-mint-dark (flat, modern icon set)
Cursor Theme
LK_Capitaine-Cursors (clean, high-DPI cursor)
Window Manager
XFWM4 with compositing and shadows
Panel Layout
Top panel with the Docklike taskbar plugin (window grouping and pinning), plus the Kodachi Cairo-Dock action launcher
Font
Noto Sans 9pt (with Noto Color Emoji)
Wallpaper
Kodachi-branded privacy-themed dark wallpapers
Boot Splash
Plymouth with Kodachi theme
Login Screen
LightDM GTK Greeter with Kodachi branding
Blue Light Filter
Redshift-GTK for automatic color temperature adjustment
Boot Menu Overview
Kodachi Desktop groups every boot entry by security tier so you can pick the right hardening profile. Use the comparison table for a quick overview.
Boot Speed Tip
The first (top) GRUB entry is Live, the lightest default profile and the fastest way to boot the ISO.
Hardening profiles that run fully from RAM (Maximum Privacy, Forensics Mode and Full Hardening) also consume more memory.
Stronger hardening profiles appear lower in the menu and may boot slower because they enable extra security controls.
Kodachi does not compromise boot-time security for faster startup by default.
If you want lower RAM usage, faster startup, or broader compatibility, select a less restrictive entry such as Live or Persistent from the boot menu.
Some commands, drivers, or services may fail under stricter hardening profiles; if something does not work, reboot and switch to a less restrictive profile.
Main Boot Entries
Mode
Tier
Persistence
Best For
Live
Tier 1
No
Quick testing, hardware diagnostics
Persistent
Tier 2
Yes
Personal devices, everyday privacy
Encrypted Persistence
Tier 3
LUKS
Long-term use with encrypted storage
CPU Hardened
Tier 3
No
Vulnerable CPUs (Spectre/Meltdown protection)
Maximum Privacy
Tier 4
No (RAM)
Anonymity operations, anti-tracking
Kernel Lockdown (confidentiality)
Tier 4
No
Kernel lockdown LSM in confidentiality mode plus module signing enforcement. Not UEFI Secure Boot, which this image supports on every entry through shim.
Forensics Mode
Tier 5
No (RAM)
Forensic analysis, volatile memory analysis
Full Hardening
Tier 5
No (RAM)
High-threat environments, maximum kernel security
Installer Entries in GRUB
Open Advanced options & fallback modes... to reach the Debian installer entries.
If you need boot-time duress nuke, select Install Kodachi (Text + Full Disk Encryption, Boot-Nuke Compatible) or Install Kodachi (Unattended + Full Disk Encryption, Boot-Nuke Compatible).
The normal GUI installer remains available for standard installs, but its encrypted path may still prompt in GRUB first and therefore block boot-time nuke before initramfs starts.
IPv6 Defaults Per Boot Tier
IPv6 is disabled at the kernel (ipv6.disable=1) on every entry in the live boot menu, so no live entry can be booted to get runtime IPv6 control. On an installed system the Kodachi security-mode entries force it off too; the stock Kodachi OS GNU/Linux entry does not add the flag.
On a live boot the IPv6 stack is therefore never initialized and /proc/sys/net/ipv6/ is absent, so health-control ipv6-enable cannot bring it back: the flag is on the kernel command line and only a different boot changes it. This is not tier-dependent and it is not something the Dashboard can override.
Layer Activation on Boot
Normal boot: Layers 02 (XFCE core) + 03 (Network GUI) are auto-loaded.
Minimal boot: add kodachi.mode=minimal to the kernel command line; optional services stay off.
All layers are included in the ISO and need no downloads.
Kodachi AutoShield
What Happens on First Boot
LightDM Login - Kodachi-branded login screen appears. Enter credentials: kodachi / Security4All. Use the keyboard/language selector in the greeter first if you need to switch layout.
XFCE Desktop - Dark-themed XFCE desktop loads with panel, taskbar, and system tray
Conky Dashboard - Real-time system monitor appears on desktop showing CPU, RAM, network, VPN, and security status
Kodachi Dashboard - Terms acceptance on first start, then the Quick Launch picker for the five cockpits (Circle, Lite Classic, ColonyOps, Vitals, SOC). The Advanced setup screen beside it holds the Settings, Mobile, AutoShield, About and Terms tabs
Already active - Encrypted DNS through dnscrypt-proxy and randomized MAC addresses are in place from boot; AutoShield runs its controls at boot only after you arm it
Automatic First-Boot Operations
dnscrypt-proxy starts and /etc/resolv.conf points to it (encrypted DNS from the first boot)
NetworkManager gives each connection a randomized MAC address, stable for that network during one boot (a connection profile can override it)
The Conky panels start, fed by the shared conky-status snapshot
The dashboard reads connectivity, IP, country and the security score, and signs in by itself only when auto-authentication is on in Settings > Dashboard > Startup
AutoShield controls run only when AutoShield is armed
AutoShield: Boot Automation
Kodachi AutoShield is the boot automation system. You choose the protection controls once, arm it, and Kodachi applies them every time it starts, in order, without a click. Open it from the AutoShield tab of the dashboard's Advanced setup screen. Arming starts a countdown; when it reaches zero the enabled controls run. Every control can also be run on its own straight away. For a control-by-control walkthrough with live pictures of the real interface, see the AutoShield chapter of the Dashboard Manual.
Category
Controls (choices)
Identity
Authenticate (re-login), Randomize Hostname (random, or reset to default), Randomize MAC Address (all interfaces, or all except the active one), Randomize Timezone (random, or synced to your exit IP)
Connectivity
Connect VPN / Proxy (WireGuard by default; OpenVPN, AmneziaWG, OpenVPN over Cloak, the four Xray variants, Hysteria2, Shadowsocks, V2Ray, Mita / Mieru, Dante, Tor through redsocks, or auto-select), Restore Network (reset MAC addresses), Recover Internet (standard or fast)
DNS
DNS Mode (DNSCrypt, Tor DNS, Pi-hole filtering, a random or a fallback resolver), DNS Hardening (DNSSEC, DoH resolvers, or both; the dashboard labels the DoH choice "DNS-over-TLS")
Tor
Torrify System (a single instance, or load-balanced round-robin, weighted or consistent-hashing over nftables, round-robin also over iptables), Exit-Node Policy (exclude 5, 9 or 14 Eyes countries), Tor Instances (restart, stop or start all), New Tor Circuit
Hardening
Harden System (standard or medium profile), Arm Kill-Switch (raises the high-alert flag; it does not watch the tunnel)
Hardware
Bluetooth, Wi-Fi, Webcam, Microphone, USB Storage, USBGuard
Run a saved Workflow profile, or connect a saved external VPN provider profile, at boot
That is 30 controls in 8 categories. Out of the box three are on: Authenticate, Randomize Hostname and Randomize Timezone. Each category has Enable all and Disable all switches, each control has a Run now button and a description toggle, and a control with choices remembers the one you picked.
Countdown, sounds and status
Timer: 60 seconds, 2, 5 or 10 minutes, 1, 3 or 6 hours, or Manual (no automatic run). 10 minutes is the default. Pause and resume keep the remaining time.
Sounds: a master switch plus Timer start, Each execute, 15s warning and All complete, each with a preview button.
Tabs: System Status (auth, IP and country, VPN, Tor, MAC, hostname, timezone, DNS, hardening and the security score), Before / After (hostname, MAC, timezone and score before and after a run, each with a copy button) and Output Logs. The refresh button cycles the automatic refresh through 30s, 60s, 2m, 5m, 10m, 1h, 2h, 5h, 12h and 24h, and the refresh icon updates everything at once.
Buttons: Execute runs the enabled controls now; Stop halts after the control that is running finishes (completed controls are not rolled back); Run again and Restart timer appear after a run; Reset reloads your saved settings and clears this run's plan, results and output.
Shield strength: 2 or fewer enabled controls read Low, 3 to 4 Medium, 5 to 6 High and 7 or more Maximum, so the three defaults read Medium.
Authentication gate: Execute stays disabled until Authenticate is enabled or you are already authenticated, because most identity and routing controls need a Kodachi account.
AutoShield Hints & Tips
Manual Review Workflow
Set the timer to Manual, read the System Status and Before / After tabs, then use each control's Run now button one at a time and check Output Logs after each run. The cleanest way to explore AutoShield without firing the whole sequence.
VPN + Tor Layering
The order matters. Let AutoShield connect the VPN first, then run Torrify System once the tunnel is up, so traffic goes through the VPN and then Tor. Reversing the order breaks Tor circuits when the VPN rewrites the routing table.
Timezone Plausibility
A random timezone can disagree with the country your IP shows. When you use a VPN with a known exit country, pick Sync to exit IP on the Randomize Timezone control so the clock matches the location you present.
Censorship-Resistant Protocols
Connect VPN / Proxy stays on WireGuard unless you choose otherwise. AmneziaWG and OpenVPN over Cloak are there for networks that block VPNs by protocol signature. With AmneziaWG the interface is awg0, so wg show stays silent on a healthy tunnel and awg show reports it. Tor through redsocks is VPN-only: connect WireGuard or OpenVPN first.
Settings Persistence
The timer, the enabled controls and their choices, the refresh interval and the sound preferences are saved to ~/.config/kodachi-dashboard/autoshield-settings.json, one copy for each login account, and survive reboots and dashboard upgrades.
DNS Privacy Toggles
DNSSEC and DoH (encrypted DNS)
Kodachi's dns-switch can enable two extra DNS-privacy features on top of DNSCrypt:
Command
Effect
Score gain
sudo dns-switch dnssec-on
Validates DNSSEC signatures via dnscrypt-proxy
+0.1
sudo dns-switch dot-on
Allows DoH (DNS-over-HTTPS) resolvers via dnscrypt-proxy
+0.2
sudo dns-switch dnssec-off / dot-off
Disable each
N/A
Both write to /etc/dnscrypt-proxy/dnscrypt-proxy.toml and restart the service. Note: these are the Kodachi-canonical commands. Do NOT manually edit /etc/systemd/resolved.conf on Kodachi (systemd-resolved is typically inactive; the encryption layer is dnscrypt-proxy).
Hardware Support Matrix
The 10.0.3 desktop image carries 37 firmware and CPU microcode packages, the same set as the terminal image, plus GPU drivers for desktop rendering.
Realtek (r8169 driver with firmware-realtek), plus standard kernel-supported chipsets (Intel e1000/igb/ixgbe, Atheros) and server NIC firmware for Broadcom NetXtreme (bnx2, bnx2x) and QLogic
Intel CPU microcode updates, AMD CPU microcode updates
Audio
PipeWire (with PulseAudio compatibility) + ALSA, Bluetooth audio through PipeWire's Bluetooth plugin, Intel SOF sound firmware
Broadcom Wireless Support - Pre-Installed
Broadcom b43 and b43legacy firmware is pre-installed in the ISO at /lib/firmware/b43/ and /lib/firmware/b43legacy/. No post-boot installation required.
Install Kodachi Desktop on your main computer or laptop. Use LibreWolf for browsing, LibreOffice for documents, and Tor Browser for sensitive research. Route your traffic through a VPN, Tor or both, with Conky showing your security posture in real time.
Example 2: Secure Development Machine
Enable the Development layer (Layer 09) for git tools, build tools and crypto libraries, and install VSCodium from the Repository Manager. Write code with Firejail sandboxing and GPG-signed commits via Kleopatra, then verify that each development tool follows the intended route and DNS policy. The routing stack cannot guarantee that every application or protocol is anonymous.
Example 3: Multimedia & Content Creation
Activate the Multimedia layer (Layer 04) for video recording with vokoscreen-ng and media playback with mpv. All content creation tools operate behind the privacy stack.
Example 4: Network Security Audit
Enable the Security GUI layer (Layer 08) for tshark packet capture, Zenmap network scanning, and EtherApe traffic visualization. Run analyses through Tor or VPN for anonymous reconnaissance.
Example 5: Air-Gapped Secure Computing
Boot from USB in Maximum Privacy mode (Tier 4). It runs in RAM and does not intentionally mount or write local disks by default, but disks that you or a tool mounts remain writable. Use KeePassXC for credential management, SiriKali for encrypted containers, and BleachBit for cleanup before shutdown.
Example 6: Virtual Machine Testing Lab
Install the Virtualization Host layer (Layer 07B) from the Repository Manager, Additional apps entry "QEMU and Virt Manager", for virt-manager and QEMU/KVM; it is not shipped in the ISO. Run additional VMs inside Kodachi Desktop for nested security testing, malware analysis in isolated environments, and network simulation.
Backup & Restore
Before you download and install a new Kodachi ISO, use the built-in Backup & Restore feature to preserve your personal files and restore them on the new system. It wraps restic for encrypted, deduplicated, versioned backups and is available from the dashboard and the command line.
From the dashboard: open Settings and select the Backup tab (the same Settings window in every cockpit). Pick an encrypted destination volume, choose what to back up, enter a repository passphrase, then use Backup now / Verify integrity, or restore from a listed snapshot.
The "What to back up" list is dynamic. It shows the standard data categories, any custom folders you have added, and common crypto wallets that are present on disk. To add a folder, use the Add custom folder control in the Backup tab, enter an absolute path, and confirm, the entry appears as a checkbox, is included in future backups, and can be removed at any time. Common wallets are auto-listed when they exist: Monero (~/.bitmonero and ~/Monero), Bitcoin Core (~/.bitcoin), Electrum (~/.electrum), and Wasabi (~/.walletwasabi). Custom entries and auto-listed wallets are persisted in ~/.config/kodachi/backup/include.list, keeping the GUI and CLI in sync. Note: wallet data stored under ~/.config is excluded by the desktop-config exclusion rule; the auto-listed wallets above all store outside ~/.config and are backed up correctly.
From the command line (same engine as the Terminal edition):
kodachi-backupbackup--target/media/usb[--allow-unencrypted]# encrypted backup to a volumekodachi-backuprestore--target/media/usb# restore into ~/Restored-<date> stagingkodachi-backuprestore--target/media/usb--in-place# overwrite originalskodachi-backupverify--target/media/usb# integrity checkkodachi-backuplist--target/media/usb# list available snapshotskodachi-backupstatus--target/media/usb# show repository statuskodachi-backupcategories# list all what-to-back-up entries as JSONkodachi-backupadd-path--path<dir># add a custom folder to the backup listkodachi-backupremove-path--path<dir># remove a custom folder from the backup list
Encryption detection. LUKS, VeraCrypt/TrueCrypt, and other dm-crypt volumes are detected automatically. You can also back up to an ordinary (unencrypted) drive, you will be warned and must opt in via the "Allow unencrypted destination" checkbox in the GUI or --allow-unencrypted on the CLI. Note: restic still encrypts the backup with your passphrase regardless; only the drive's full-disk-encryption layer is absent. The repository passphrase is never stored.
Data only, by design. It backs up Documents, Downloads, Pictures, Videos, Music, Desktop, Public, Templates, plus ~/.gnupg, ~/.ssh, password stores and the LibreWolf profile. It deliberately excludes desktop and system configuration (~/.config, ~/.cache, ~/.local, ~/.kde) so that restoring onto a newer ISO can never break the fresh desktop.
Safe restore. By default files land in a ~/Restored-<date> staging folder, leaving your live system untouched, copy back what you need. Use the in-place option only when you want files written straight to their original locations.
Kodachi packages come from the project's own APT repository, published as three channels. Stable (repo) is the released line every installation tracks by default. Beta (repo-beta) runs ahead of stable and is where a release is proven before it becomes stable. Dev (repo-dev) sits behind HTTP Basic Auth and is not open to the public.
You do not have to edit apt sources by hand. The Repository Manager window switches channel, refreshes the package lists and shows what is installed against what the selected channel offers. Launch it from the Cairo Dock action launcher on the desktop, which fronts the Repository Manager alongside the other one-click Kodachi actions.