A full Debian desktop transformed into a privacy command center.
Use Kodachi Desktop when you want a visual dashboard, browser tools, AutoShield guidance, and day-to-day privacy controls from a complete live or installed environment.
XFCE desktopDashboard modesAutoShieldLive or installed
A full-featured desktop OS based on Debian 13 (Trixie) with the XFCE desktop environment, purpose-built for daily privacy-focused computing.
Ships with the full Kodachi binary suite pre-installed, the Kodachi Dashboard, a Lua-powered Conky system monitor, and a complete GUI application suite spanning browsers, office, multimedia, security tools, and development environments.
18+ months of development. Built for privacy-conscious desktop users.
linux-kodachi-xfce-9.0.1-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 from USB drive without installation (portable, leaves no traces)
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=linux-kodachi-xfce-9.0.1-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=linux-kodachi-xfce-9.0.1-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
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 18+ months on Debian 13 (Trixie), Kodachi Desktop combines the terminal security stack with a complete XFCE desktop environment. The system bundles 444 curated packages: 244 terminal-level security and networking packages plus 200 desktop GUI applications, each serving a specific privacy role. (Fully resolved with dependencies, the installed package count is significantly higher.)
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
Privacy by Design
Every network connection leaving Kodachi Desktop is privacy-protected by default. The system enforces privacy from the moment the kernel loads.
11 Routing Protocols
WireGuard, OpenVPN, Shadowsocks, V2Ray, Xray (VLESS/Reality), Hysteria2, Mieru (MITA), Dante, and Microsocks. Any protocol can be layered with system-wide Tor routing via tor-switch torrify-system-nftables-dns, encrypting every packet including DNS queries.
DNSCrypt Auto-Config
Encrypted DNS activates automatically on first boot via dns-switch. No manual configuration required. The system selects optimal servers and enforces encrypted resolution from the moment the desktop loads.
MAC Randomization
Hardware identity is randomized on every boot via health-control. Your network adapter presents a different MAC address each session, preventing device fingerprinting across networks.
VPN Kill Switch
Blocks all outbound traffic instantly if the VPN connection drops. Prevents IP leaks during connection interruptions, ensuring your real address is never exposed to the network.
System Hardening
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. Isolates browser, email, and messaging apps from each other and from sensitive system resources.
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.
Binary Security Suite
Binary Security Suite
Kodachi Desktop ships a full set of high-performance binaries that form a unified security control plane. Each binary uses strict error handling with no .unwrap() calls in production code.
health-control
237 commands: System monitoring, emergency panic modes, security scoring, kill switches, MAC randomization, hostname management, and memory security controls.
tor-switch
110 commands: Tor lifecycle management, load balancing, exit node control, system-wide torrification, and circuit management.
dns-switch
44 commands: DNS server management, DNSCrypt configuration, Pi-hole integration, and encrypted resolution enforcement.
routing-switch
29 commands: VPN and Tor routing control, protocol switching between 11 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 changes and restores correct ownership across critical system paths.
All binaries communicate through logs-hook, which writes structured JSON for forensic analysis. The kodachi-dashboard exposes the entire suite through a unified GUI.
The Dashboard
Kodachi Dashboard
Four Modes. One Mission. Total Control.
The Kodachi Dashboard orchestrates 589 commands across 25 Rust binaries with zero GUI freezing. Choose your interface: gamified security ring, first-boot AutoShield wizard, compact command center, or professional multi-panel workstation.
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, anti-censorship transports, Tor, DNSCrypt, or a workflow-backed layered setup. 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.
CIRCLE MODE
Gamified Security Ring
720×720px
~230MB RAM
Beginner-Friendly
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
25Commands
2Services
10Profiles
~180MB RAM
LITE MODE
RECOMMENDED
Compact Command Center
1128×774px
~230MB RAM
Intermediate
Collapsible sidebar with 14 tabs providing quick access to essential security operations, AI chat, command library, system monitoring, and direct terminal access with live output display.
14 Sidebar Tabs: Actions, AI Chat, Library, Health, Resources, Processes, Network, Firewall, Startup, Logs, Passwords, Settings, About, Help
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
147Commands
18Services
14Tabs
~230MB RAM
FULL MODE
Professional Workstation
1800×1000px
~380MB RAM
Advanced Users
Multi-panel command center with 22 tabs across 4 major sections. Supports drag-and-drop command queuing, resizable panels, and parallel/sequential execution modes for power users.
4 Major Sections: Essentials (9 subtabs), Advanced (11 service tabs), System Monitor (7 subtabs), AI Integration
Drag & Drop Queue: Build complex operation sequences with reordering, parallel/sequential execution, and danger level badges
Signed binary suite: Complete access to health-control (237 commands), tor-switch (110 commands), routing-switch (29 commands), dns-switch (44 commands), online-auth, workflow-manager, and more
589Generated Commands
24Services
22Tabs
~380MB RAM
Core Infrastructure Across All Modes
All four modes share the same powerful backend: 589 commands orchestrated across 25 Rust 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
Mode Comparison Matrix
Mode
Window Size
RAM Usage
Interface
Skill Level
Primary Use
Circle
720×720px
~230MB
Gamified Ring
Beginner
Quick security setup
Lite
1128×774px
~230MB
14-Tab Sidebar
Intermediate
Daily operations
Full
1800×1000px
~380MB
22-Tab Workstation
Advanced
Power user workflows
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 mode mirrors the same fallback logic for operators who want one-click recovery and temporary backup tunnels without opening Full mode.
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
Switches between Circle, Lite, and Full mode. Move between quick setup and the full workstation without relaunching. 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.
Service / Logs Header > Swap Icon
Swaps the position of the Service panel and the Logs panel. Put logs on top if you spend more time reading output than issuing commands.
Service / Logs Header > Collapse Icon
Hides one panel so the other fills the full area. Expand the logs panel to full width 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.
Sidebar Essentials, 9 Subtabs
11 tips
Essentials > 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.
Essentials > 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.
Essentials > 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 > Hardening
Five toggle categories: Internet (firewall, port blocking), Hardware (USB protection, Bluetooth kill), Services (disable daemons), Security (kernel hardening), Privacy (telemetry blocking). Toggle all five for maximum hardening.
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
Tor instance overview, exit-node country selection, circuit management, and quick torrification controls. Daily Tor operations without opening the full Advanced > Tor Switch tab.
Essentials > DNS
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).
Essentials > Library
Searchable command library across all 589 commands. Type a keyword like "leak" or "hostname" and the library shows every matching command with its service, danger level, and description.
Essentials > Emergency
KillSwitch, Nuke, Oniux isolation, Proxy Services, panic controls, integrity verification, and secure wipe tools. If something goes wrong, start here.
Essentials > AI
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
Dashboard > 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.
Dashboard > 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.
Dashboard > 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.
Dashboard > 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.
Dashboard > 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.
Dashboard > Logs
System logs (syslog, auth.log, kernel messages) with filtering. Review authentication attempts, kernel warnings, and service failures after security incidents.
Dashboard > 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.
Advanced Service Tabs, Full Mode
14 tips
Routing Switch routing-switch
11 auto-scored protocols (plus xray-vmess legacy fallback). WireGuard, OpenVPN, 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 vmess:///vless:///ss:///trojan:///hysteria2:///tuic:// URI schemes plus Clash YAML and sing-box JSON subscriptions). 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
110 commands. Tor instances, exit-node country selection, load-balanced torrification, circuit rotation, and system-wide DNS-through-Tor. Deeper control than Essentials > Tor.
DNS Switch dns-switch
44 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. Critical after any routing change.
Health Control health-control
237 commands. Identity randomization, internet recovery, security hardening, panic modes (soft/medium/hard), kill switches, USB protection, memory wiping, 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 > 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 > 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.
Settings > Emergency > Duress Password (Nuke)
Secondary password that triggers the destructive duress protocol. Displays a fake "System Update" while silently destroying sensitive data. Last-resort coercion response.
Settings > Emergency > Emergency Shortcuts
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 > 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 > 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 > Essentials > Actions and click Randomize MAC, Randomize Hostname, and Randomize Timezone to create a fresh identity. 2. Go to Sidebar > Essentials > Tor and rotate the exit node to a different country. 3. Open Sidebar > Advanced > DNS Leak and run a leak test to confirm DNS goes through Tor. 4. Check Sidebar > Dashboard > 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 > Essentials > 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 > Advanced > Routing Switch and disconnect the active VPN protocol. 2. Switch to Sidebar > Advanced > Tor Switch and run torrify-system-nftables-dns to route all traffic through Tor. 3. Open Sidebar > Advanced > IP Fetch to confirm the IP is a Tor exit node. 4. Run Sidebar > Advanced > 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 KillSwitch for instant network cut, 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 (Full mode): 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, Table, and Raw in the logs panel. JSON for structured data, Table for multi-row results.
Panel Presets (Full mode): Switch between Balanced, Logs-focused, Output-expanded, and Minimal layouts.
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 > 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 > Auto Internet Recovery
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 > Timeout Configuration
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 Options
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 8 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
Dashboard > Network > 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.
Dashboard > 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.
Dashboard > System Info > 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 Servers > Database Features
Filter DNS servers by category: reputable, normal, encrypted, fallback. Search by name or IP. Each server shows a color-coded health score. Fetch fresh servers from remote sources, choosing 50, 100, or all results. Toggle between compact and grid views.
Essentials > Tor > Instance Management
Click any Tor instance for detailed config. Adjust load-balancing weights per instance. Use the Exit Node Modal to select countries, regions, or alliances. Batch-create instances with naming patterns. Set per-instance auto-IP-change timers.
Settings > Dashboard > Window & Startup
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 > Notifications
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 the Full and Lite dashboards and a modal in the Circle dashboard. 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
Monitor, Advanced, and Essentials sections 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 mode is for first-time users and quick security checks, it presents a gamified ring interface in a compact 720x720 window. Lite mode adds a 14-tab sidebar for daily operations at 1128x774. Full mode is the professional workstation at 1800x1000 with all 22 tabs, command queue, drag-and-drop, and 4 panel presets. Start in Lite and upgrade to Full when you need the Advanced service tabs or command queuing.
Discovery Without Memorization
If you do not know which binary provides a feature, open Sidebar > Essentials > Library and search by keyword. The Library indexes all 589 commands from all 25 Rust 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 and enable all five categories (Internet, Hardware, Services, Security, Privacy). Then open Sidebar > Essentials > Actions and run Randomize MAC, Randomize Hostname, and Randomize Timezone. Finish by verifying with Sidebar > Advanced > DNS Leak and Sidebar > Dashboard > Network.
AI Chat Across All Modes
The AI Chat button in the top status bar works in Circle, Lite, and Full modes. 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 to access the AI Commander and configure AI daemons.
Browser Privacy
Browser Privacy Configuration
Kodachi treats browsers as high-risk attack surfaces and applies aggressive privacy hardening. Both LibreWolf and Tor Browser run inside Firejail sandboxes with telemetry elimination, fingerprinting defense, and tracking protection at the configuration level.
LibreWolf
Primary clearnet browser with 16 pre-installed privacy extensions
Font Fingerprint Defender (blocks enumeration), WebRTC disabled (prevents IP leaks), Canvas protection, User-Agent randomization
DNS-over-HTTPS (DoH)
TRR mode 3 (fail-closed) forces all DNS through encrypted channels with zero plaintext fallback. Excludes localhost/kodachi.local for VPN/Tor compatibility
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
Firejail Sandboxing
Restricted filesystem access (read-only /usr, /lib, /bin; write-only ~/.tor-browser), seccomp filtering, disabled network namespaces to preserve Tor routing
.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 with Firejail Isolation
Both browsers run in Firejail sandboxes with restricted filesystem access, seccomp filtering to block dangerous syscalls, and disabled network namespaces to preserve VPN/Tor routing. This dual-browser approach separates clearnet browsing (LibreWolf) from onion services (Tor Browser), preventing cross-contamination of browsing profiles and reducing fingerprinting surface area.
.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
LibreWolf blocks .onion domains by default (per RFC 7686). To access onion services through Kodachi Browser, you must first torrify the system and then configure both the browser and the FoxyProxy extension.
Step 1: Torrify the system with DNS redirection
Choose any of these methods:
Lite Dashboard
Open Sidebar > Essentials > Tor. Under the Torrify Mode group, select "Single instance with DNS" (or "Load balanced multi instance"), then click Torrify System.
Advanced
Open Sidebar > Advanced > Tor Switch. Go to the Firewall tab, select nftables, and click Enable Torrification. For DNS-only routing, use the DNS tab and click Enable DNS over Tor. For load-balanced mode, use the Load Balancing tab to set the mode then go to the Overview tab and click Torrify.
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. Set 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. Instances are listed with their ports, IPs, and exit countries.
Advanced
Open Sidebar > Advanced > Tor Switch > Instances tab. The grid shows SOCKS, Ctrl, DNS, Trans, IP, and Exit columns for 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 at least 10 Tor instances simultaneously (MIN_INSTANCES_FOR_LOAD_BALANCE=10; no hard upper cap). 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 > Tor Actions dropdown > Exit Countries submenu > select a country (e.g., Germany (DE)) or region (e.g., Random Europe, 5-Eyes). Applies to all instances.
Advanced
Sidebar > Advanced > Tor Switch > Exit Nodes tab > choose between Countries, Regions, Alliances, or Random > select target > choose Apply to All Instances or a specific instance > click Apply Exit Node. Alternatively, go to the Instances tab, right-click any instance, and select Set Exit Node.
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 > Load Balancing group > select Round-Robin, Consistent, or Weighted > click Apply. Then under the Torrify Mode group, select "Load balanced multi instance" and click Torrify System.
Advanced
Sidebar > Advanced > Tor Switch > Load Balancing tab > select Round Robin, Weighted, or Consistent Hashing. Set per-instance weights if using Weighted. Then go to the Overview tab and click Torrify, or use the Firewall tab to enable torrification.
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 up to 10 independent Tor instances in parallel. 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 (Advanced > Tor Switch > Auto IP Change) 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
AI-Powered Intelligence
Kodachi Desktop integrates an AI operations suite running entirely through anonymous channels. AI queries, model interactions, and automated tasks are significantly harder to trace to your identity or location.
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 AI requests through anonymous channels. All AI operations can route through Tor for stronger anonymity.
Dashboard Fortress
Dashboard Fortress
The Kodachi Dashboard is locked behind a multi-layer authentication system. Password, TOTP two-factor, recovery codes, and automated threat response combine to create an impenetrable access control system that makes unauthorized dashboard access virtually impossible.
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.). Both factors 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. Full audit trail for forensic review. Logs are tamper-resistant and timestamp-verified.
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 PanicIRREVERSIBLE
Initiates full panic mode sequence. Wipes sensitive data, kills network, clears RAM. See Emergency Response for details.
Lockout → Block → Shutdown → Panic
Nuclear Options
Nuclear Options
When compromise is imminent or confirmed, Kodachi provides irreversible data destruction capabilities that no forensic team can recover from. Two independent nuke systems (LUKS Nuke at boot and Dashboard Duress Protocol at login) ensure data destruction is always 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
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 data is permanently gone. The adversary sees only a corrupted partition with no evidence of intentional destruction.
Dashboard Duress Protocol (Nuke Password)
Set a secret duress password in the dashboard. When entered at the login screen instead of the real password, the dashboard shows a convincing "System Update" screen while destruction runs silently in the background. The attacker sees fake package installation progress bars and realistic update text. Zero audit trail. Complete plausible deniability.
Fake Update Screen: Displays 13 simulated update phases with realistic Debian package names, version numbers, progress percentages, and completion messages. Indistinguishable from a real system update. By the time the "update completes," all sensitive data is destroyed.
Destroy Kodachi, Sidebar Icon
A red Destroy Kodachi icon (skull) is the last icon at the bottom of the dashboard's left sidebar, present in the Full, Lite, and Circle dashboards. 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: Instantly destroys the encryption header(s) of active LUKS-encrypted devices. The disk becomes permanently unreadable before any further action runs.
2Full Dashboard Nuke: Kills the network, wipes RAM and clipboard, shreds sensitive files, destroys the boot record / MBR / EFI, and forces an immediate power-off.
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. The button shows no fake update screen; destruction starts immediately once confirmed.
IRREVERSIBLE: Once triggered, this action cannot be stopped or undone. The LUKS header wipe alone makes the encrypted data permanently unrecoverable.
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 > Password Security), and the LUKS Nuke in the Power/Essentials section (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.
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
Shortcuts require holding 3+ modifier keys + a trigger key for 1500ms (configurable). Auto-repeat is rejected. Prevents accidental activation.
Hardware Corroboration
X11 key grabs are verified against raw /dev/input events within 100ms. Synthetic input (XTEST) cannot trigger emergency actions.
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 (Phase 1): Global shortcuts require an X11/XFCE session. Wayland sessions are detected and fail closed. Configure shortcuts from the Dashboard Settings > Emergency Shortcuts panel.
Wipe Intensity Comparison
Mode
Passes
Speed
Standard
Use Case
Fast
1-pass zero
~30s
Single overwrite
Quick destruction when time is critical
Secure
3-pass DoD
~45s
DoD 5220.22-M
Standard secure wipe meeting military spec
Paranoid
7-pass
~60s
Extended overwrite
Maximum destruction for highest threat scenarios
Storage-Aware Wiping
SSD
blkdiscard --secure: TRIM-based secure erase triggers the drive's built-in secure wipe. Instant on drives supporting secure discard.
NVMe
nvme format --secure: NVMe secure format command utilizes the drive's cryptographic erase capability for complete destruction.
HDD
shred multi-pass: Traditional multi-pass overwriting with random data patterns. Necessary for magnetic media where TRIM is not available.
Emergency Response
Emergency Response
Three escalation levels of panic mode let you choose between recoverable defensive measures and irreversible destruction. Network kill switches provide instant isolation. Every action is designed for split-second activation when seconds matter.
Panic Soft
Recoverable. Defensive lockdown without data loss.
Block all internet traffic (nftables)
Stop Tor instances
Clear DNS cache
Randomize MAC addresses
Randomize hostname
Clear clipboard & recent files
Recovery: recover-internet restores connectivity
Panic Medium
Partially reversible. Adds data wiping to lockdown.
Everything in Panic Soft, plus:
Wipe all browser data
Destroy SSH/GPG keys
Wipe messaging app data
Clear all application logs
Wipe temporary files & caches
Secure RAM wipe
Recovery: Network recoverable, wiped data is gone
Panic Hard
IRREVERSIBLE. Total destruction and shutdown.
Everything in Panic Medium, plus:
Destroy cryptocurrency wallets
Wipe email client data
Overwrite free disk space
Wipe swap partition
Full RAM destruction
System power-off
Recovery: None. All data permanently destroyed.
Panic Soft→Panic Medium→Panic Hard→IRREVERSIBLE
Network Kill Switches
Command
Method
Effect
block-internet --method nftables
nftables
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/firewalld
Reject all traffic via system firewall (user-facing tools)
block-internet --method interfaces
Interface down
Bring down all network interfaces (physical disconnection)
block-internet --method all
All methods
Apply all four methods simultaneously for maximum guarantee
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 or manual kill switch activation, use recover-internet which attempts 9 recovery methods automatically: flush nftables, flush iptables, reset UFW, bring up interfaces, restart NetworkManager, restart systemd-networkd, flush DNS, restore resolv.conf, and restart DHCP. Falls back through each method until connectivity is restored.
Identity Randomization
Identity Randomization
Every identifying attribute of your system can be randomized on demand. MAC address, hostname, timezone, and IPv6 settings combine to make your machine appear as a completely different device on every connection.
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
mac change-all: Randomize all interfaces
mac force-change: Force change even if busy
mac change <iface>: Target specific interface
mac reset: Restore original hardware MAC
mac show: Display current vs. original
Hostname Randomization
7 categories of fake hostnames to blend in with any network:
Windows: DESKTOP-XXXXXXX patterns
Linux: ubuntu-server, fedora-ws, etc.
Apple: MacBook-Pro, iMac patterns
Fiction: Creative fictional names
Gaming: Gaming console patterns
Tech: Generic tech device names
Nature: Nature-inspired names
Timezone Management
8 timezone categories with intelligent selection:
IP-based sync: Match timezone to Tor exit node
Random: Pick completely random timezone
Americas / Europe / Asia / Africa / Pacific / Middle East: Region-specific random selection
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:
Tier 1-3 boot: IPv6 stack loaded at boot; Dashboard toggle flips it on/off at runtime via sysctl (no reboot)
Tier 4-5 hardening boot (Maximum Privacy, Forensics, Full Hardening): IPv6 disabled at kernel level (ipv6.disable=1); Dashboard cannot re-enable until you reboot into a lower tier
health-control ipv6-enable: reverses all of the above; warns if a Tier 4-5 cmdline is blocking it
Installed systems: persistent state lives in /etc/default/grub.d/50_kodachi_ipv6.cfg and survives reboots after update-grub
Data Destruction
Data Destruction Arsenal
Beyond the nuke sequences, Kodachi provides granular control over data destruction. Wipe specific categories, target individual applications, scrub RAM against 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
Firefox, Chromium, Tor Browser, Brave: history, cookies, cache, saved passwords, form data, downloads
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: System chooses optimal method
Automatic on Shutdown
RAM wipe integrates with systemd shutdown hooks. When the system powers off or reboots, RAM is automatically scrubbed before the power-off sequence completes. Defends against cold boot attacks where an adversary freezes RAM chips to extract encryption keys.
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
Hardening Score
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 enabled independently, and three security profiles provide preset configurations from standard protection to full paranoid isolation.
Balanced protection for daily use. Network-safe settings that don't break common applications. Enables kernel, network, and memory hardening. Suitable for browsing, communication, and general computing.
Paranoid
Maximum isolation for high-threat scenarios. All 7 modules at maximum settings. Network-isolated, sandboxed processes, aggressive filesystem restrictions. May break some applications. Use when security trumps convenience.
Break-Monitoring
Active breach detection profile. Enhanced monitoring, file integrity tripwires, process anomaly detection, real-time alerting. Designed for detecting active compromise attempts. Generates alerts on suspicious activity.
Integrated Security Tools
Kloak
Keystroke anonymization. Randomizes key event timing to defeat keylogger-based timing analysis attacks. Makes keyboard fingerprinting impossible.
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: Live, Persistent, Encrypted Persistence, CPU Hardened, Forensics, DMA Protection. Not available in Full Hardening or Secure Boot Mode. On installed systems, Maximum Privacy and Standard Hardened also 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 (Secure Boot Mode, Full Hardening, Maximum Privacy) enforce signed kernel modules, and Tirdad ships as an unsigned out-of-tree DKMS module (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, Forensics, or DMA Protection). 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 unsigned or tampered module. The locked-down kernel refuses Tirdad not because Tirdad is bad, but because it cannot cryptographically verify it, 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. To use Tirdad, disable Secure Boot from your BIOS/UEFI firmware settings first.
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. Detects kernel rootkits, backdoors, and hidden processes. Cross-validates results between engines.
ClamAV
Open-source antivirus engine. Real-time scanning, scheduled scans, and on-demand file checking. Signature database updated via Tor for anonymous updates.
Security Operations Center
SOC, Neural Monitor
The Security Operations Center (SOC) page gives you a live neural map of host-security telemetry. Open it from the Radar icon in the left navigation (immediately after System Health) in both the Advanced and Lite dashboards.
The Neural Map
The central canvas shows a security score core surrounded by eight 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 Rootkit, 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.
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.
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.
Read-only view. The SOC is a monitoring and visualization layer over Kodachi's existing security telemetry. It does not change system state. Use health-control commands or the dashboard action panels to act on findings.
USB & Hardware
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
PulseAudio/PipeWire source mute + module unload
Blocks audio surveillance and room monitoring
Bluetooth
rfkill block + kernel module blacklist
Eliminates Bluetooth tracking, pairing attacks, and BLE beacons
WiFi
Module blacklist per chipset
Prevents WiFi probe requests that reveal device identity
Hardware RNG Verification
Verify that hardware random number generators (RDRAND, RDSEED) are functioning correctly. Tests entropy quality and detects potentially compromised RNG implementations. Critical for cryptographic key generation.
Entropy Pool Monitoring
Monitor /proc/sys/kernel/random/entropy_avail in real-time. Low entropy starves cryptographic operations. The system alerts when entropy drops below safe thresholds and can feed additional entropy sources.
Boot Integrity Checking
Verify boot partition integrity against known-good hashes. Detects Evil Maid attacks, bootloader tampering, and initramfs modifications. Compare checksums on every boot cycle.
Watch-Guard
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, every connection is monitored and contained.
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
Daemon Mode
WatchGuard runs as a persistent background daemon. Configurable polling intervals, automatic recovery attempts, and integration with the dashboard notification system. Survives user session changes. Starts on boot.
Auto-Block Methods
When a watch triggers, internet is blocked using 4 layered methods: nftables (drop all), iptables (reject all), UFW/firewalld (deny all), and interface down. All four applied simultaneously for guaranteed isolation.
System Monitoring (Full Mode)
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. Traffic is forced through a dedicated Tor circuit with no possibility of leaking to the real network. Unlike proxychains or torsocks which rely on library preloading, Oniux uses kernel-level namespace isolation that cannot be bypassed by the application.
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.
Security Models
Security Models & Layered Anonymity
Kodachi Desktop includes 96 pre-built security workflows plus unlimited custom workflows via workflow-manager. Below are 18 example workflows by anonymity level covering WireGuard, OpenVPN, Shadowsocks, Hysteria2, V2Ray, Xray, and Mita. Workflows 1-3 (Triple VPN + Tor) provide maximum anonymity. Workflows 4-8 (Double VPN + Tor) offer ultra anonymity. Workflows 9-11 (Single VPN + Double Tor) provide very high anonymity. All profiles are in /opt/kodachi/dashboard/hooks/config/profiles/.
initial_terminal_setup_wireguard_torrify - WireGuard + Tor torrification
initial_terminal_setup_auth_torrify_only - Authentication + Tor torrification
Execute with:sudo workflow-manager run <profile-name>
Workflow Selection Guide - Organized by Anonymity Tiers
TIER 1: Maximum Anonymity - Triple VPN + Tor (Workflows 01-03)
- Anonymity Level: Ultra++ (6/6) - Triple VPN protection with Tor torrification
- Best for: Ultimate anonymity, extreme threat models, state-level adversaries, whistleblowing, maximum deniability
- Configuration: Router VPN → Host VPN (Mullvad/ProtonVPN/NordVPN) → Kodachi VPN (WireGuard/OpenVPN/Shadowsocks) → Torrified System → Tor DNS
- Speed: Slowest to Very Slow
TIER 2: Ultra Anonymity - Double VPN + Tor (Workflows 04-08)
- Anonymity Level: Ultra (5/5) - Double VPN with Tor torrification
- Best for: Different VPN providers, avoiding single-point surveillance, investigative journalism, activist operations, censorship bypass with maximum protection
- Configuration: Normal Router → Host VPN (Mullvad/ProtonVPN/NordVPN/ExpressVPN) → Kodachi VPN (OpenVPN/Shadowsocks/V2Ray/Hysteria2) → Torrified System → Tor DNS
- Speed: Slow to Moderate
TIER 3: Very High Anonymity - Single VPN + Double Tor (Workflows 09-11)
- Anonymity Level: Very High (4.5/5) - Double Tor circuits or Router + Guest VPN + Tor
- Best for: Extreme anonymity requirements, .onion operations, dark web research, sensitive communications, maximum deniability
- Configuration: Kodachi VPN (Xray/WireGuard) → Torrified → Double Tor Circuits OR Router VPN → Kodachi VPN → Torrified System
- Speed: Very Slow to Slow
TIER 4: High Anonymity - Double VPN without Tor (Workflows 12-14)
- Anonymity Level: High (4/5) - Double VPN layer
- Best for: Censorship bypass, DPI evasion, advanced anti-detection, high-performance with strong privacy
- Configuration: Normal Router → Host VPN (Mullvad/ProtonVPN/ExpressVPN) → Kodachi VPN (Shadowsocks/Hysteria2/Xray-VLESS-Reality) → DNScrypt
- Speed: Good to Very Good
TIER 5: Moderate-High Anonymity - Single VPN + Tor (Workflows 15-17)
- Anonymity Level: Moderate-High (3.5/5) - Single VPN with Tor
- Best for: Hostile network environments, general privacy, anonymous browsing, daily privacy operations, secure communications
- Configuration: Kodachi VPN (Hysteria2/V2Ray/Shadowsocks) → Torrified System → Tor DNS
- Speed: Moderate
TIER 6: Moderate Anonymity - Single VPN Only (Workflow 18)
- Anonymity Level: Moderate (3/5) - Single VPN with encrypted DNS
- Best for: Online banking, shopping, business email, general secure browsing, fast performance requirements
- Configuration: Kodachi VPN (OpenVPN) → DNScrypt
- Speed: Fast
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 official documentation, and Kodachi security research. These workflows represent comprehensive threat modeling from maximum anonymity to secure financial operations.
Technical Specs
Technical Specifications Dashboard
Core System Specifications
Component
Details
Base System
Debian 13 (Trixie)
Architecture
amd64 (x86_64)
Desktop Environment
XFCE 4
Display Manager
LightDM with GTK Greeter
ISO Size
~5GB (full desktop with GUI applications)
Curated Packages
444 packages (244 terminal + 200 desktop GUI; uncommented entries across both list files)
Terminal Packages
244 security-focused terminal packages (uncommented entries in terminal.list.chroot)
GUI Packages
200 desktop GUI packages (uncommented entries in gui-xfce.list.chroot)
Kodachi Binaries
31 bundled binaries: 28 pre-installed in /opt/kodachi/dashboard/hooks/ (20 core + 8 KAICS AI suite) plus 3 companion runtimes
Kodachi bundles 31 binaries: 28 are pre-installed at /opt/kodachi/dashboard/hooks/ (the 20 core binaries below plus the 8-binary KAICS AI suite) and 3 companion runtimes ship alongside them. 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.
Kodachi Desktop uses a modular layer system that lets you activate feature sets on demand, keeping the base system lean while providing access to the full application suite when needed.
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
"Enable Virtualization" button
~400MB
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: Layer 02 only. Desktop shows "Enable" buttons for each optional layer
VM detected: Layer 07A (VMware guest tools) auto-enabled when running inside a VM
All terminal.list.chroot packages (networking, VPN, security, firmware)
AI & Intelligence
Optional
KAICS tools (ai-cmd, ai-gateway, and related binaries)
Routing Protocols
Supported Routing Protocols
Kodachi Desktop ships with 11 auto-scored routing protocols (plus xray-vmess as a legacy fallback) via the routing-switch binary, covering everything from battle-tested VPNs to advanced censorship-resistant transports.
Routing Protocol Coverage
Category
Protocols & Features
VPN Protocols
OpenVPN (industry-standard, AES encryption), WireGuard (modern, ChaCha20 encryption) with kill switch and DNS leak protection
Redsocks (transparent Tor routing), SOCKS proxy configuration, TransPort routing, DNS over Tor, System-wide torrification (can run on top of any existing VPN service). 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
Kodachi Desktop supports system-wide torrification that can run on top of any existing VPN service. 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 RiseVPN and VPNGate, and you can also use other commercial or free providers if you prefer.
Security & Privacy Features
Security & Privacy Features
Kodachi Desktop inherits the full terminal security stack and adds GUI-specific protections for desktop environments.
Lua-powered desktop monitor with 5 panels, 22 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 > Conky Control and turn off Enable Conky now to hide the desktop overlay for the current session, or use Conky Disable from the Lite Dashboard when you want the lowest CPU use on older or low-power hardware.
Privacy Screenshot Mode
The Lite Dashboard diagnostics menu 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
22Scripts
8Cairo Gauges
7Config Files
Resources + Gauges
280px × Full Height
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, latency to privacy DNS
Bandwidth Ring: White, combined throughput
Security Status
320px × Full Height
4×6 Binary Grid: AUTH/VPN/TOR/DNS visual status (lit = active)
External IP: Country code + flag via ip-fetch
Security Score: 0-100 aggregate from 7 categories with adaptive max
Systemd Watchdog: Auto-restart on unresponsive panels (15s timeout) or memory leaks (>500MB)
DPI Scaling: Auto-detects Xft.dpi, scales fonts/gauges for HiDPI displays
Rofi Menu
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
15 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.
Hardware Support
Hardware Support Matrix
Kodachi Desktop bundles 30+ firmware packages inherited from the terminal base, plus GPU drivers for desktop rendering.
Intel CPU microcode updates, AMD CPU microcode updates
Audio
PulseAudio + ALSA, Bluetooth audio (pulseaudio-module-bluetooth)
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.
Customization
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
LK_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 Docklike taskbar plugin (window grouping and pinning)
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
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 (especially Forensics and Maximum Privacy) 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
Secure Boot Mode
Tier 4
No
UEFI Secure Boot, module signing enforcement
Forensics Mode
Tier 5
No (RAM)
Forensic analysis, volatile memory analysis
Full Hardening
Tier 5
No
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
Starting with Kodachi 9.0.1, the IPv6 kernel stack is enabled by default on Tier 1-3 entries and on the fallback/compatibility entries. The Dashboard IPv6 control (and health-control ipv6-disable / ipv6-enable) flips IPv6 on or off at runtime via sysctl with no reboot required.
Only three top-tier hardening entries keep the ipv6.disable=1 kernel flag:
Maximum Privacy (Tier 4)
Forensics Mode (Tier 5)
Full Hardening (Tier 5)
On those three entries the IPv6 stack is never initialized, /proc/sys/net/ipv6/ is absent, and the Dashboard cannot re-enable IPv6 without rebooting into a lower tier. Pick a Tier 1-3 entry if you need runtime IPv6 control.
Layer Activation on Boot
Normal boot: Layers 02 (XFCE core) + 03 (Network GUI) are auto-loaded.
Minimal boot: Only Layer 02. Desktop shows enable buttons for optional layers.
All layers are included in the ISO and activate instantly without downloads.
AutoShield
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 - Welcome screen with terms acceptance, dashboard mode selection (Full, Lite, or Circle), optional startup privacy settings, and network connectivity detection
Automatic Setup - DNSCrypt auto-configuration, binary verification, online authentication, and system status collection
Automatic First-Boot Operations
Binary deployment verification (validates all bundled core binaries)
DNSCrypt auto-configuration (encrypted DNS on first run)
Online authentication (Kodachi services and premium features)
System status collection (IP, geolocation, security score)
Kodachi AutoShield is the guided first-boot wizard tab on the Kodachi Dashboard's welcome screen: a countdown-driven privacy hardening console for identity randomization, secure routing, DNS setup, and live verification, also reachable from the Lite-mode sidebar and the Full-mode Advanced section.
First-Boot Automation
Fortify Your Digital World
AutoShield combines timed execution, live resource telemetry, identity before/after comparison, and shield scoring in one guided screen instead of scattering those checks across multiple tools.
8 Timer ModesLive TelemetryIdentity CompareShield Meter
Countdown Timer Ring
Auto
Animated circular countdown (60s / 2min / 5min / 10min / Manual) with step progress tracking. Auto-executes enabled steps when timer reaches zero. Shows real-time execution progress with animated ring fill.
System Resources Bar
Live
Real-time telemetry flanking the timer ring: CPU%, memory usage, swap, uptime, temperature, open ports, network I/O (tx/rx), disk I/O (read/write). Updates every 2 seconds.
Shield Strength Meter
Visual
Segmented bar visualization showing protection level (Low/Medium/High/Maximum) based on number of enabled steps. Pulsing glow animations with color-coded threat levels (red/yellow/green).
Before/After Panel
Compare
Shows identity values before and after execution: Hostname, MAC address, Timezone, Security Score. Each value has a copy button for easy clipboard access.
Auth Gate Protection
Premium
Non-authenticated users can run Authenticate, Refresh Status, Recover Internet, and Enable DNSCrypt. The remaining identity and routing actions require successful Kodachi authentication first.
Persistent Settings
JSON
Timer duration, step toggles, auto-refresh interval, and auto-close preference persist across reboots via JSON settings file. Maintains user configuration between sessions.
9 Configurable Security Steps
Step
Command
Default
Before/After Tracking
Authenticate with Kodachi Services
online-auth authenticate --relogin
Enabled
Auth status (Not Authenticated → Authenticated)
Randomize Hostname
health-control set-random-hostname
Enabled
Hostname (kodachi → random-string)
Randomize MAC Address
health-control mac-force-change
Enabled
MAC address (real → randomized)
Randomize Timezone
health-control set-random-timezone
Enabled
Timezone (UTC → random zone)
Harden PC Security
health-control security-harden
Disabled
Security Score (before → after score)
Recover Internet Connectivity
health-control recover-internet
Enabled
Network state (blocked → restored)
Quick Connect WireGuard
routing-switch connect wireguard
Enabled
VPN status (Disconnected → Connected)
Torrify System + DNS
tor-switch torrify-system-nftables-dns
Disabled
Tor status (Inactive → Active + Torrified)
Refresh System Status
Fetches current IP, geolocation, auth, VPN, Tor, DNS status
Enabled
All current system values updated
Shield Strength Protection Levels
Level
Steps Enabled
Visual Effect
Description
Low
0-2 steps
Red pulsing bar
Minimal protection. System identity exposed, no anonymity layers.
Medium
3-4 steps
Yellow pulsing bar
Partial protection. Some identity randomization, basic network security.
High
5-6 steps
Green pulsing bar
Strong protection. Full identity randomization, VPN active, DNS encrypted.
Maximum
7+ steps
Bright green pulsing bar
Ultimate protection. All anonymity layers active, system hardened, Tor routing enabled.
Quick Launch Buttons
Apps
6 instant-launch applications:
• Kodachi Dashboard - Main control panel
• Kodachi Browser - Privacy-hardened browser
• Oniux Browser - LibreWolf launched through Oniux isolation
• Oniux Terminal - Terminal launched through Oniux isolation
• Tor Browser - Anonymous browsing via Tor
• RiseVPN - VPN management application
Configurable system status refresh:
• 30 seconds, 1 minute, 2 minutes, 5 minutes, 10 minutes, 1 hour, 2 hours, 5 hours, 12 hours, 24 hours
Automatically updates IP, geolocation, VPN status, Tor status, DNS mode, and security metrics at selected interval.
System Status Tab
Info
Real-time telemetry display:
Auth status, IP address, geolocation with country flag, VPN status, Tor status, MAC address, Hostname, Timezone, DNS mode, Hardening modules, Security Score. All values have copy-to-clipboard buttons.
Output Log Tab
Debug
Live execution output:
Real-time command output with timestamps, duration tracking, success/failure indicators, and scrollable history. Shows stdout/stderr from all executed steps for debugging and verification.
Support Overlay
Donate
Manual support panel:
Click the binary 01 widget in the AutoShield header to open a binary-rain support overlay with donation and sharing links. It does not auto-popup during normal use.
AutoShield Hints & Tips
AutoShield packs significant control into a compact interface. This operator map covers every interactive element, hidden submenu, and non-obvious combination so you can use AutoShield precisely instead of just accepting the defaults.
Header & Display Controls
4 tips
Header Right > Online / Offline Badge
Shows live network state. Hover the badge to see a tooltip with your current IP address, VPN status, Tor status, DNS resolver, connection speed, and geolocation. The fastest pre-flight check before pressing Execute. If the tooltip shows an unexpected IP or "Direct" instead of "VPN," stop and fix routing before proceeding.
Header Right > Binary 01 Widget
Opens a binary-rain support overlay with donation and sharing links. Manual access only, it never auto-popups during normal operation. Safe to ignore during security workflows.
Header Right > ZapOff / Sparkles Icon
Toggles reduce-animations mode for AutoShield. Click once for a calmer, lighter interface. Reduces the timer ring animation, shield glow, and step transition effects. Good for low-power hardware or when animations are distracting during manual review.
Header Right > Sun / Moon Icon
Switches between light and dark themes. Use light theme on high-ambient-light displays or projectors. Dark theme (default) is optimized for low-light operational environments.
Timer, Sound & Execution Controls
9 tips
Timer Section > Timer Selector
Choose from 8 countdown modes: 60s, 2 min, 5 min, 10 min (default), 1 hour, 3 hours, 6 hours, or Manual. Use 60s for rapid automated hardening on boot. Use Manual when you want to inspect every step before execution. Use longer timers (1-6 hours) as scheduled re-hardening intervals.
Timer Ring Center > Pause / Resume
Pauses or resumes the active countdown without resetting it. Pause when you need more review time. The countdown freezes at its current position. Resume when ready. This does not change the selected timer duration.
Under the Timer > Sound Controls
Five independent toggles: Sound (master), Timer start, Each execute (per-step notification), 15s warning, All complete. Enable Each execute and All complete for audible feedback when working in another window. Disable Sound entirely for silent operation in shared spaces.
Footer > Execute
Starts running all enabled steps in sequence. The main "go" button. Only runs steps that are toggled on. Check the step list before pressing.
Footer > Skip
Skips all remaining steps and exits the AutoShield wizard. Use when you have already run the steps you need and want to leave quickly without waiting for the rest of the sequence.
Footer > Reset
Reloads factory defaults and reapplies saved default step values. This is a full reset, not just clearing execution state, your step toggles will revert to the shipped defaults. Use when you want to undo manual toggle changes and return to the standard configuration.
Footer > Stop
Halts execution immediately after the current step finishes. Use when you spot a problem mid-run. Steps already completed are not rolled back.
Footer > Restart
Restarts the countdown timer from the beginning. Does not re-run steps that already completed. Use when you want more review time before the next step executes, or to extend the timer after pausing.
Auth Banner > Run Auth
Runs Kodachi authentication directly from the AutoShield wizard. Unlocks restricted steps (identity randomization, VPN, torrification) without leaving the wizard tab. If the auth banner appears, you must authenticate before those steps can execute.
Tabbed Panel & Status Monitoring
5 tips
Tabbed Panel > System Status
Live system snapshot: IP, VPN tunnel, Tor circuits, DNS resolver, security score, CPU/memory/network metrics. Your pre-flight dashboard. Review this tab before touching the step list. If System Status already shows a VPN connected and DNS encrypted, you may only need identity randomization steps.
Tabbed Panel > Before / After
Side-by-side comparison of identity values before and after execution: Hostname, MAC address, Timezone, Security Score. Each value has a copy button. The proof that AutoShield actually changed your identity. If the "After" column matches "Before," the step failed or was skipped. Copy values for external records.
Tabbed Panel > Output Logs
Live execution output with timestamps, duration tracking, success/failure indicators, and scrollable history. Shows stdout/stderr from all steps. Essential for troubleshooting. When a step shows a red failure indicator, switch to Output Logs to read the actual error message. Clear output between runs for a clean view.
Tab Header > Refresh-Interval Button
Cycles through 10 intervals: 30s, 60s, 2m, 5m, 10m, 1h, 2h, 5h, 12h, 24h. Controls how often System Status and Before/After panels refresh automatically. Set to 30s during active configuration, 1h+ for passive monitoring.
Tab Header > Refresh Icon
Triggers an immediate status refresh regardless of the auto-refresh interval. Click after making a manual change outside AutoShield (e.g., connecting VPN from the terminal) to see the updated status immediately.
Step Controls & Hidden Submenus
11 tips
Steps Header > Enable All / Disable All
Toggle icons on the right side of the steps header. Fastest way to build a custom execution profile. Click "Disable all" first, then enable only the steps you want. This is how you create a minimal targeted run.
Any Step Row > Main Toggle
Include or exclude that step from the execution sequence. Build a custom run instead of accepting the default plan. Disabled steps are completely skipped, no partial execution.
Any Step Row > Play Button
Run that single step immediately, independent of the timer. Surgical changes, run only "Randomize MAC" without touching DNS or VPN. The step executes instantly and shows its result in the Output Logs tab.
Randomize Timezone > Sync Timezone (2nd Play)
Instead of a random timezone, uses public-IP geolocation to set a timezone matching your VPN exit location. Use this when your timezone must be plausible for the IP you are presenting.
Harden PC Security > Paranoid Mode (2nd Play)
Applies a stronger hardening profile than the default. Disables more services, tightens more kernel parameters, and sets more restrictive firewall rules. Use for high-threat scenarios.
Recover Internet > Chevron Menu (3 Options)
Fast Recovery (quick reconnect), Forced Recovery (clears all firewall rules and resets routing), Routing Recovery (rebuilds routing tables). Try Fast first, escalate to Forced if it fails.
Enable DNSCrypt > Chevron Menu (10+ Options)
Legacy/Modern DNS mode, DNS status, DNSCrypt status, Safe DNS repair, Forced DNS repair, Tor DNS routing, DNS leak test, Pi-hole toggle, Random DNS selection, Fallback DNS. The most feature-dense submenu in AutoShield.
Connect WireGuard > Chevron Menu (Protocols)
Switch to OpenVPN, V2Ray, Shadowsocks, Xray (multiple variants), Hysteria2, Mieru (MITA), Dante, Microsocks, or remote Tor routing, all without leaving AutoShield. Remote Tor is VPN-only: connect WireGuard or OpenVPN first, then the remote Tor route layers Tor on that tunnel. Kodachi never exposes the worker Tor SOCKS port on a public IP (an open Tor SOCKS proxy gets abused), so it cannot be connected standalone.
Torrify System + DNS > Chevron Menu (Tor)
Start/stop/restart all Tor instances, main Tor controls, load-balanced torrification, instance listing, iptables + DNS torrification. Full Tor management from inside AutoShield.
Finished Step Row > Inline Detail Panel
Copy and Dismiss controls. Copy captures the step output to clipboard. Dismiss clears the visual indicator. Use Copy before Dismiss if you need the output for records.
Step Rows > Per-Step Stop Controls
Several steps have dedicated stop/undo actions accessible from their chevron menus: Reset MAC to factory (undo MAC randomization), Stop Tor DNS (revert DNS routing), Stop All Instances (shut down all Tor instances), and Stop Main Tor (stop the primary Tor process). These let you surgically reverse individual steps without resetting the full sequence.
Footer Launchers & Shield Strength
7 tips
Footer > Dash
Leaves the AutoShield wizard for the rest of the Kodachi Dashboard. Quick path to the full dashboard for operations the wizard does not cover (e.g., process monitoring, firewall inspection, advanced workflows).
Footer > K Browser
Launches Kodachi Browser (LibreWolf with privacy hardening). Pre-hardened browser for general privacy browsing after AutoShield completes.
Footer > O Browser
Launches Oniux Browser (Tor-isolated browser). Browser with embedded Tor circuit isolation. Use for sensitive browsing that requires per-application Tor routing.
Footer > O Term
Launches Oniux Terminal (Tor-isolated terminal). Terminal with embedded Tor circuit. Run CLI tools through isolated Tor without system-wide torrification.
Footer > Tor
Launches the standard Tor Browser for Tor-native browsing with its own circuit management.
Footer > Rise
Launches RiseVPN. Quick access to the RiseVPN client for an alternative VPN connection.
Shield Strength Meter (Sidebar)
Segmented bar showing protection level: Low (red), Medium (yellow), High (green), Maximum (pulsing green). Visual feedback on how many steps are enabled. 7 default steps = Maximum. Disabling steps drops the meter. Use this to gauge your protection level at a glance before executing.
Scenarios & Workflows
4 tips
Manual Review Workflow
Inspect everything before changing the system: 1. Set the timer to Manual. 2. Review the System Status tab for current state. 3. Review the Before / After tab to see baseline values. 4. Use individual step play buttons to run only the steps you want, one at a time. 5. Check Output Logs after each step for errors. 6. Click the refresh icon in the tab header to update System Status after each change. The cleanest way to explore AutoShield without firing the full automatic sequence.
Fastest Boot-to-Protected Workflow
1. Leave all 7 default steps enabled (Authenticate, Randomize Hostname, Randomize MAC, Randomize Timezone, Enable DNSCrypt, Connect WireGuard, Refresh Status). 2. Set the timer to 60s for immediate execution after boot. 3. Enable the All complete sound toggle so you know when it finishes. 4. After completion, verify the Before / After tab shows changed values for hostname, MAC, and timezone. 5. Optionally enable Recover Internet, Harden PC Security, and Torrify System for maximum protection.
DNS Troubleshooting via Submenu
When DNS breaks after a routing change: 1. Open the Enable DNSCrypt row > chevron menu. 2. Click DNS Status to check current resolver state. 3. Try Safe DNS Repair first, restores encrypted DNS without breaking active tunnels. 4. If that fails, use Forced DNS Repair to reset all DNS config. 5. Run DNS Leak Test from the same submenu to verify queries are encrypted. 6. If Tor is active, switch to Tor DNS to route DNS through Tor circuits.
Switching Protocols Without the Dashboard
1. Open the Connect WireGuard row > chevron menu. 2. Select any alternative: OpenVPN, Shadowsocks, Xray, Hysteria2, or others. 3. The selected protocol connects automatically. The step name updates to reflect the active protocol. 4. To add Tor, open the Torrify System row > chevron menu and select Load-balanced torrification. 5. Hover the Online / Offline badge in the header to verify the new routing chain.
Default Configuration
Enabled by default: Authenticate, Randomize Hostname, Randomize MAC, Randomize Timezone, Enable DNSCrypt, Connect WireGuard, Refresh Status (7 steps = Maximum shield strength).
Disabled by default: Recover Internet (not needed when network is already up), Harden PC Security (applies system-wide kernel and service changes), Torrify System + DNS (can conflict with WireGuard on first boot, connect VPN first, then torrify separately).
Default timer: 10 minutes with auto-execution enabled.
VPN + Tor Layering
To run VPN and Tor simultaneously, the order matters. Let AutoShield connect WireGuard first (or any VPN protocol via the submenu). After VPN is active, manually run Torrify System + DNS from its play button or chevron menu. This routes traffic through VPN first, then Tor. Reversing the order causes Tor circuits to break when VPN modifies the routing table.
Timezone Plausibility
Random timezones create a mismatch between your IP geolocation and system clock. If you are using a VPN with a known exit country, use the Sync Timezone button (second play button on the Randomize Timezone row) instead of the default random timezone. This queries your public IP geolocation and sets a timezone that matches, making your identity more plausible to sites that check timezone consistency.
Shield Strength Meter
The shield strength meter has 4 levels: Low (1-2 steps), Medium (3-4 steps), High (5-6 steps), Maximum (7+ steps). The meter reacts in real time as you toggle steps on and off. Aim for Maximum (all 7 defaults enabled) for standard operation. The meter pulses with a green glow at Maximum to confirm full protection.
Settings Persistence
All AutoShield configuration, timer duration, step toggles, auto-refresh interval, sound preferences, and theme choice, is saved to <hooks_dir>/config/autoshield-settings.json. Settings persist across reboots, system updates, and dashboard upgrades. You configure AutoShield once, and it remembers your preferences permanently.
Install Kodachi Desktop on your main computer or laptop. Use LibreWolf for browsing, LibreOffice for documents, and Tor Browser for sensitive research. All traffic routed through VPN + Tor with Conky monitoring your security posture in real-time.
Example 2: Secure Development Machine
Enable the Development layer (Layer 09) for VS Code, git tools, build tools, and crypto libraries. Write code with Firejail sandboxing, GPG-signed commits via Kleopatra, and all network traffic anonymized through the routing stack.
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). Runs entirely in RAM, leaves no traces on host hardware. Use KeePassXC for credential management, SiriKali for encrypted containers, and BleachBit for cleanup before shutdown.
Example 6: Virtual Machine Testing Lab
Enable the Virtualization Host layer (Layer 07B) for virt-manager and QEMU/KVM. Run additional VMs inside Kodachi Desktop for nested security testing, malware analysis in isolated environments, and network simulation.
Debug Tools
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 the support team. It collects boot logs, hardware specs, network configuration, Kodachi service status, and more.
Privacy First
The collector does not capture IP addresses, passwords, browsing data, or personal files. WiFi credentials and MAC addresses are automatically redacted. 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 the support team on Discord or via the contact form.
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).
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 (available in both the Full and Lite dashboards). 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.