Kodachi Desktop Debian XFCE

Kodachi Desktop XFCE Edition

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 (Tauri 2 + Svelte 5), a Lua-powered Conky system monitor, and a complete GUI application suite spanning browsers, office, multimedia, security tools, and development environments. Supports KAICS plus ai-gateway as optional add-ons, and kodachi-claw for anonymous autonomous AI agent operations with embedded Tor circuits. 18 months of development. Built for privacy-conscious desktop users.

XFCE Desktop Privacy-First AI-Powered Tor-Ready Dark Theme Kodachi Claw

Download & Installation First Release: 26 February 2026 9.0.1 | Desktop last updated 08 April 2026 - build #58

Download ISO

Download the latest Kodachi Desktop XFCE ISO directly. Full desktop experience with privacy tools pre-configured.

9.0.1-amd64 ~5GB

Download ISO

Access the complete archive of Kodachi releases, checksums, and documentation on SourceForge.

Open SourceForge

ISO Integrity Verification

Verify the downloaded ISO file integrity using the SHA256 checksum below to ensure secure installation:

      SHA256 Checksum:
      cb4b0e37f026f38a808b5477ef5538ea11e355ed9fcc11ce4f4e2c339621593d
    

Verification Command:
sha256sum linux-kodachi-xfce-9.0.1-amd64.iso

GPG Signature Verification Available

SourceForge also provides GPG signature files for cryptographic verification. Download the signature files from the same location:

linux-kodachi-xfce-9.0.1-amd64.iso.sig - GPG signature file
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.

Login Credentials

Username: kodachi

Password: Security4All

These are the live-session kodachi account credentials. root login is disabled and does not use this password.

Create Bootable USB

Tool	Platform	Multiboot	Best For
Ventoy	Linux Windows	Yes	Drag-and-drop multiple ISOs onto one USB. Install once, reuse forever.
Rufus	Windows	No	Industry-standard. Select ISO, select USB, write in DD or ISO mode.
Etcher	Linux Windows macOS	No	Simplest UI. Three-step flash: select, target, burn.
YUMI	Windows	Yes	Add multiple OSes to one USB, one at a time. Boot menu included.
UUI	Windows	No	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

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 includes 460 curated packages: 268 terminal-level security and networking packages plus 192 desktop GUI applications, each serving a specific privacy role.

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 (Tauri 2 + Svelte 5).

Privacy by Design

Every network connection leaving Kodachi Desktop is privacy-protected by default. The system enforces privacy from the moment the kernel loads.

12+ 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

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

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

213 commands — System monitoring, emergency panic modes, security scoring, kill switches, MAC randomization, hostname management, and memory security controls.

tor-switch

107 commands — Tor lifecycle management, load balancing, exit node control, system-wide torrification, and circuit management.

dns-switch

27 commands — DNS server management, DNSCrypt configuration, Pi-hole integration, and encrypted resolution enforcement.

routing-switch

18 commands — VPN and Tor routing control, protocol switching between 12+ transport methods, 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 (Tauri 2 + Svelte 5) exposes the entire suite through a unified GUI.

Kodachi Dashboard

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.

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

4 Emergency Controls: Routing Recover, Internet Recover, Restart Tor, Secure Shutdown

11 Commands

5 Services

7 Segments

~230 MB RAM

Countdown-driven setup wizard that launches automatically 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

25 Commands

2 Services

10 Profiles

~180 MB RAM

Collapsible sidebar with 15 tabs providing quick access to essential security operations, AI chat, command library, system monitoring, and direct terminal access with live output display.

15 Sidebar Tabs: Actions, AI Chat, Library, Health, Resources, Processes, Network, Firewall, Startup, Logs, Passwords, Settings, About, Help

12 Primary Actions: Login/Logout, WireGuard, Torrify, DNSCrypt, Random DNS, Harden, MAC/Hostname/Timezone randomization, Recovery controls

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

147 Commands

10 Services

15 Tabs

~230 MB RAM

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

4 Panel Presets: Balanced split, logs-focused (70% logs), output-expanded, minimal sidebar with custom layout saving

24 Rust Binaries: Complete access to health-control (213 commands), tor-switch (107 commands), routing-switch (18 commands), dns-switch (27 commands), online-auth, workflow-manager, and more

517+ Commands

24 Services

22 Tabs

~380 MB RAM

Core Infrastructure Across All Modes

All four modes share the same powerful backend: 517+ commands orchestrated across 24 Rust binaries with async execution to prevent GUI freezing. Security score aggregates 5 categories (Core, Network, Hardening, Device, Advanced) with color-coded risk levels: Green (80+), Yellow (60-79), Red (<60).

Async Execution Danger Level Badges 4 Output Formats Auto-Refresh IP + Flag + Auth Status Mode Switcher

Mode	Window Size	RAM Usage	Interface	Skill Level	Primary Use
Circle	720×720px	~230MB	Gamified Ring	Beginner	Quick security setup
Lite	1128×774px	~230MB	7-Tab Sidebar	Intermediate	Daily operations
Full	1800×1000px	~380MB	23-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.

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

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

Launches Kodachi AutoShield. Re-opens the first-boot automation wizard from 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.

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 517+ 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, Kodachi Claw (AI agent with embedded Tor), 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.

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.

Routing Switch `routing-switch`

12+ protocols. WireGuard, OpenVPN, Shadowsocks, V2Ray, Xray (VLESS/Reality), Hysteria2, Mieru, Dante, Microsocks, Tor routing, protocol benchmarking, config export/QR tooling, and the new VPNGate fetch/list/connect/export workflow. The main workbench for switching transport layers.

Tor Switch `tor-switch`

107 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`

27 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`

213 commands. Identity randomization, internet recovery, security hardening, panic modes (soft/medium/hard), kill switches, USB protection, memory wiping, and scoring.

Online Auth `online-auth`

Authentication management: login, logout, session status, token refresh, heartbeat monitoring.

IP Fetch `ip-fetch`

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

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 AutoShield 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 > 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. Expand each item to view its full output. Use keyboard arrows for navigation.

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.

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 three sizes: default, small (faster), and large (more accurate). Local models provide complete offline AI capability with no cloud dependency.

Essentials > AI Commander > Claw Tab

Kodachi Claw provides persistent AI daemon integration. Configure AI providers (Claude, OpenAI, etc.), manage channels, toggle automation, and control the AI gateway with firewall and policy controls. Includes onboarding wizard for first-time setup.

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.

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.

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 15-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 517+ commands from all 24 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 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.

Core Extensions

uBlock Origin (8 filter lists), ClearURLs (tracking parameter removal), Decentraleyes (local CDN resources), Cookie AutoDelete (tab-close cleanup)

Multi-Account Containers

4 isolated contexts with strict cookie separation: Personal, Work, Banking, Shopping

Fingerprinting Defense

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

Search Engine Hardening

Removed 6 tracking engines (Google, Bing, Yahoo, Amazon, eBay, Wikipedia). Default: DuckDuckGo with privacy parameters (!safeoff, !ads-off)

Privacy Testing Bookmarks

20+ testing links: IP detection (whatismyip, ipleak.net), DNS leaks (dnsleaktest.com), WebRTC leaks, fingerprinting (amiunique.org, EFF Panopticlick)

16 Extensions

8 Filter Lists

4 Containers

20+ Test Links

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

3 Security Modes

100% Onion Native

3 Tor Hops

0 Telemetry

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.

Read-Only System Directories Write-Only Browser Profiles Seccomp Syscall Filtering Network Namespace Disabled Separate Cookie Jars Zero Profile Cross-Contamination

Accessing .onion Addresses

.onion domains are special addresses that exist only within the Tor network. Regular DNS servers cannot resolve them, so browsers and applications need specific configuration to reach onion services. Kodachi provides two methods depending on your workflow.

Method 1: Tor Browser (Simplest)

Open Tor Browser from the XFCE panel or AutoShield 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 Configuration Native .onion Support Own Tor Circuits No 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	Launch AutoShield 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:

`network.dns.blockDotOnion`	false
`network.proxy.type`	0 (no proxy — system handles routing)

Step 3: Configure FoxyProxy (pre-installed extension)

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 — it is more reliable than iptables for transparent proxy and DNS redirection.

Load-Balanced Torrify (torrify-system-nftables-load-balanced)

When using load-balanced torrification (round-robin, weighted, or consistent-hashing), Kodachi runs up to 10 Tor instances simultaneously. 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. The same client always reaches the same Tor instance, providing session affinity.

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 this does not cause Tor-over-Tor

The nftables/iptables torrification rules exclude localhost (127.0.0.0/8) from the TransPort redirect. When FoxyProxy sends traffic to 127.0.0.1:10000, the connection stays local and reaches Tor's SOCKS port directly — it is not redirected through the TransPort a second time. The result is a single Tor layer, not double routing.

AI-Powered Intelligence

Kodachi Desktop integrates an AI operations suite running entirely through anonymous channels. AI queries, model interactions, and automated tasks cannot be traced to your identity or location.

kodachi-claw is an autonomous AI agent runtime operating through embedded Tor circuits. Every API request routes through dedicated Tor circuits, making correlation impossible for AI providers. 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 route through Tor for complete anonymity.

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 Lockout REVERSIBLE

Lock dashboard for configurable duration. User must wait before retrying. No data affected. Auto-unlocks after timeout.

2

Block Until Recovery RECOVERY CODE

Lock dashboard indefinitely. Requires recovery code or system-level intervention to unlock.

3

System Shutdown POWER CYCLE

Immediately powers off the machine. All volatile data in RAM is lost. Requires physical power-on to resume.

4

Trigger Panic IRREVERSIBLE

Initiates full panic mode sequence. Wipes sensitive data, kills network, clears RAM. See Emergency Response for details.

Lockout → Block → Shutdown → Panic

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).

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.

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.

Nuke Execution Paths

1 Authentication — Validate nuke password + one-time token

2 Network Kill — Block all internet via nftables/iptables

3 Tor Shutdown — Stop all Tor instances and circuits

4-7 Parallel Destruction — Browser wipe, credential wipe, logs wipe, temp/cache wipe (concurrent)

8 RAM Wipe — Secure memory clearing (sdmem/kodachi-wiper)

9 Shutdown — Power off or reboot

Uses privileged helper binary with one-time token validation. Falls back to individual phase execution if helper unavailable.

1 Initialization — Detect storage types (SSD/NVMe/HDD)

2 Network Kill — Kill all network interfaces

3 Tor Shutdown — Terminate all Tor processes

4-10 Parallel Wipe — Browsers, credentials, SSH/GPG keys, crypto wallets, messaging, logs, cache (concurrent)

11 Swap Wipe — Secure swap partition clearing

12 Free Space — Overwrite free disk space

13 RAM Wipe — Multi-method memory destruction

14 Shutdown — Power off system

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

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

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

MAC 00:1A:2B:3C:4D:5E

Hostname kodachi-desktop

Timezone America/New_York

IPv6 2001:db8::1

→

After

MAC F2:7C:9A:11:B8:03

Hostname DESKTOP-K4N92TX

Timezone Asia/Tokyo

IPv6 Disabled

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 complete IPv6 management:

ipv6 disable — Disable via GRUB + sysctl
ipv6 enable — Re-enable if needed
Reboot recommended after changes
Prevents all IPv6 traffic leak vectors

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

Credentials

SSH keys, GPG keyrings, password stores, KeePassXC databases, authentication tokens

Crypto Wallets

Bitcoin, Monero, Ethereum wallets — wallet files, transaction history, key stores

Messaging

Signal, Session, Pidgin, Thunderbird — message databases, contact lists, media files

System Logs

Journal, syslog, auth.log, kern.log, application logs — complete audit trail elimination

Disk Targets

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

System Hardening & Security Score

Kodachi calculates a real-time Security Score (0–100) across five categories. Seven hardening modules can be enabled independently, and three security profiles provide preset configurations from standard protection to full paranoid isolation.

Security Score

80+

Excellent

60-79

Moderate

<60

Needs Attention

Category	Checks	What It Measures
Core	VPN, Tor, DNS, firewall status	Whether fundamental privacy layers are active
Network	DNS leak, IPv6 leak, WebRTC, routing	Network-level information leak vectors
Hardening	Kernel, filesystem, process, memory	System-level security hardening status
Device	USB, webcam, microphone, Bluetooth	Hardware attack surface control
Advanced	Sandboxing, integrity, authentication	Advanced security features and monitoring

7 Hardening Modules

Kernel Hardening

Restrict kernel module loading, disable kexec, protect /proc, enforce BPF JIT hardening, disable unprivileged user namespaces

Process Isolation

Restrict ptrace scope, enforce YAMA LSM, limit core dumps, hide kernel pointers, restrict dmesg access

Filesystem Protection

Restrict hardlinks/symlinks, enforce noexec on /tmp, mount options hardening, file permission auditing

Network Hardening

SYN cookies, ICMP redirect blocking, source routing disabled, reverse path filtering, TCP timestamps disabled

Memory Protection

ASLR enforcement, NX bit verification, stack canary checks, KASLR status, mmap randomization

Monitoring

Process monitoring, file integrity checking (AIDE), rootkit scanning (rkhunter + chkrootkit), antivirus (ClamAV)

Sandboxing

AppArmor profiles, Firejail sandboxing, namespace isolation, seccomp filters, capability dropping

Security Profiles

Standard

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.

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.

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.

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 & Layered Anonymity

Kodachi Desktop includes 92 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/.

Workflow Comparison Matrix

Chain: ISP → Router VPN → Host Mullvad VPN → Kodachi WireGuard (VM NAT) → Torrified System → Tor DNS

Anonymity: Ultra++ (6/6 - Triple VPN) Speed: Slowest

Ideal for: Ultimate anonymity, extreme threat models, maximum deniability, state-level adversaries.

sudo routing-switch connect wireguard sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Router VPN → Host ProtonVPN → Kodachi OpenVPN (VM NAT) → Torrified System → Tor DNS

Anonymity: Ultra++ (6/6 - Triple VPN) Speed: Slowest

Ideal for: Whistleblowing, state-level adversaries, journalist protection, maximum operational security.

sudo routing-switch connect openvpn sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Router VPN → Host NordVPN → Kodachi Shadowsocks (VM NAT) → Torrified System → Tor DNS

Anonymity: Ultra++ (6/6 - Triple VPN) Speed: Very Slow

Ideal for: Maximum obfuscation, defeating DPI in hostile networks, evading advanced surveillance.

sudo routing-switch connect shadowsocks sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Normal Router → Host Mullvad → Kodachi OpenVPN (VM NAT) → Torrified → Tor DNS

Anonymity: Ultra (5/5) Speed: Slow

Ideal for: Different VPN providers, avoiding single-point surveillance, investigative journalism.

sudo routing-switch connect openvpn sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Normal Router → Host ProtonVPN → Kodachi Shadowsocks (VM NAT) → Torrified → Tor DNS

Anonymity: Ultra (5/5) Speed: Slow

Ideal for: Censorship bypass with double VPN + Tor, evading DPI, hostile network environments.

sudo routing-switch connect shadowsocks sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Normal Router → Host NordVPN → Kodachi V2Ray (VM NAT) → Torrified → Tor DNS

Anonymity: Ultra (5/5) Speed: Moderate

Ideal for: Traffic obfuscation, triple anonymity layer, defeating advanced network analysis.

sudo routing-switch connect v2ray sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Normal Router → Host ExpressVPN → Kodachi Hysteria2 (VM NAT) → Torrified → Tor DNS

Anonymity: Ultra (5/5) Speed: Moderate

Ideal for: High-performance with maximum anonymity, restrictive network circumvention.

sudo routing-switch connect hysteria2 sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Kodachi VPN (anonymous node) → Tor → Torrified System → Tor DNS

Anonymity: Ultra (5/5) Speed: Slow

Ideal for: Investigative journalism, activist operations, secure communications.

sudo routing-switch connect openvpn sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Kodachi Xray (forced traffic) → Torrified System → Tor DNS

Anonymity: Very High (4.5/5) Speed: Very Slow

Ideal for: Extreme anonymity requirements, .onion operations, dark web access.

sudo routing-switch connect xray sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Kodachi WireGuard → Torrified System → Tor DNS

Anonymity: Very High (4.5/5) Speed: Slow

Ideal for: Dark web research, sensitive communications, enhanced privacy.

sudo routing-switch connect wireguard sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Router VPN → Kodachi WireGuard (VM via NAT) → Torified System → Tor DNS

Anonymity: Very High (4.5/5) Speed: Slow

Ideal for: Maximum deniability with physical isolation, secure operations.

sudo routing-switch connect wireguard sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Normal Router → Host Mullvad → Kodachi Shadowsocks (VM NAT) → DNScrypt

Anonymity: High (4/5) Speed: Good

Ideal for: Censorship bypass with double VPN layer, evading DPI.

sudo routing-switch connect shadowsocks sudo dns-switch switch --names dnscrypt-cloudflare health-control net-check

Chain: ISP → Normal Router → Host ProtonVPN → Kodachi Hysteria2 (VM NAT) → DNScrypt

Anonymity: High (4/5) Speed: Very Good

Ideal for: High-performance double VPN for restrictive networks, streaming with privacy.

sudo routing-switch connect hysteria2 sudo dns-switch switch --names dnscrypt-quad9 ip-fetch

Chain: ISP → Normal Router → Host ExpressVPN → Kodachi Xray-VLESS-Reality (VM NAT) → DNScrypt

Anonymity: High (4/5) Speed: Good

Ideal for: Advanced anti-detection with Xray Reality, defeating sophisticated censorship.

sudo routing-switch connect xray sudo dns-switch switch --names dnscrypt-quad9 health-control security-score

Chain: ISP → Kodachi Hysteria2 (forced traffic) → Torrified System → Tor DNS

Anonymity: Moderate-High (3.5/5) Speed: Moderate

Ideal for: Hostile network environments, censorship bypass with good performance.

sudo routing-switch connect hysteria2 sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Kodachi V2Ray → Torrified System → Tor DNS

Anonymity: Moderate-High (3.5/5) Speed: Moderate

Ideal for: General privacy and anonymous browsing, traffic obfuscation.

sudo routing-switch connect v2ray sudo tor-switch torrify-system-nftables-dns

Chain: ISP → Kodachi Shadowsocks (anonymous node) → Tor → Tor DNS

Anonymity: Moderate-High (3.5/5) Speed: Moderate

Ideal for: Daily privacy operations, secure communications, DPI evasion.

sudo routing-switch connect shadowsocks sudo tor-switch start-tor-dns-nftables

Chain: ISP → Kodachi OpenVPN (forced traffic) → DNScrypt

Anonymity: Moderate (3/5) Speed: Fast

Ideal for: Online banking, shopping, business email, general secure browsing.

sudo routing-switch connect openvpn sudo dns-switch switch --names dnscrypt-quad9 health-control net-check

Protocol-Specific Initial Setup Workflows

Kodachi Desktop includes ready-to-use initial setup profiles for multiple routing protocols:

VPN Protocols:

initial_terminal_setup_openvpn_only - OpenVPN connection setup
initial_terminal_setup_wireguard_only - WireGuard connection setup

Anti-Censorship Protocols:

initial_terminal_setup_shadowsocks_only - Shadowsocks proxy setup
initial_terminal_setup_v2ray_only - V2Ray traffic obfuscation
initial_terminal_setup_xray_vless_only - Xray VLESS protocol
initial_terminal_setup_xray_trojan_only - Xray Trojan protocol
initial_terminal_setup_xray_vless_reality_only - Xray VLESS Reality
initial_terminal_setup_hysteria2_only - Hysteria2 high-performance

Proxy Servers:

initial_terminal_setup_dante_only - Dante SOCKS5 server
initial_terminal_setup_mita_only - Microsocks lightweight SOCKS5

Tor Combinations:

initial_terminal_setup_tor_only - Tor-only setup
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

Evidence: For detailed analysis, read the Tor Project's official documentation on Tor+VPN configurations.

Source Information

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 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)
Total Packages	~464 packages (270 terminal + 194 desktop GUI)
Terminal Packages	270 security-focused terminal packages (from `terminal.list.chroot`)
GUI Packages	194 desktop GUI packages (from `gui-xfce.list.chroot`)
Kodachi Binaries	29 pre-installed binaries in `/opt/kodachi/dashboard/hooks/` (core + AI + companion runtimes)
Theme	LK_Material-Black-Lime (dark)
Icons	LK_Newaita-Reborn-Mint-Dark
Cursor	LK_Capitaine-Cursors
Font	Noto Sans 9pt
Browsers	LibreWolf (primary) + Tor Browser
Kernel	6.16+
Boot Support	BIOS + UEFI + Secure Boot
Installer	Calamares graphical installer + GRUB Debian-installer entries (text, encrypted, unattended)
Login Credentials	Username: `kodachi` / Password: `Security4All`
Sudo Access	Passwordless sudo enabled

Pre-Installed Kodachi Binaries

All 29 bundled Kodachi binaries are pre-installed at /opt/kodachi/dashboard/hooks/, including the full AI suite and companion runtimes. Launch the complete security toolkit instantly without additional setup.

Core Binaries

health-control tor-switch dns-switch dns-leak routing-switch ip-fetch online-auth integrity-check permission-guard logs-hook deps-checker oniux online-info-switch conky-status workflow-manager global-launcher kodachi-claw kodachi-dashboard tun2socks-linux-amd64

AI Suite (KAICS)

ai-cmd ai-trainer ai-learner ai-admin ai-discovery ai-scheduler ai-monitor ai-gateway zeroclaw zeroclaw-desktop

Desktop Applications

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.

Always-On Applications (Layer 02 - XFCE Core)

Category	Applications
Desktop	XFCE 4, Thunar file manager, Double Commander
Browsers	LibreWolf (primary), Tor Browser, Onioncircuits
Terminals	Kitty, Tilix, XFCE4 Terminal
Editors	Geany + plugins, Mousepad
Security	Firetools (Firejail GUI), SiriKali (encryption), Kleopatra (GPG)
Network	NetworkManager GUI, OpenVPN/VPNC plugins, RiseUp VPN
System	Conky system monitor, GNOME Disks, Baobab, GParted, System Monitor
AI Desktop	ZeroClaw Desktop (Tauri companion app for ZeroClaw AI agent)
Utilities	Galculator, Ristretto image viewer, Atril PDF viewer, Engrampa, GTKHash
Display	LightDM, Plymouth boot splash, Redshift (blue light filter)
Audio	PulseAudio, PavuControl mixer, ALSA
Installer	Calamares graphical installer, Debian-installer boot entries, GDebi package installer

Optional Layer Applications

Layer	Category	Applications
03	Network GUI	Remmina, FileZilla, Transmission, uGet, Syncthing, OnionShare
04	Multimedia	mpv, vokoscreen-ng, gThumb, guvcview
05	Office	LibreOffice, Atril PDF viewer, pdftk-java, gedit
06	Printing	CUPS printing system, HP drivers, Brother/Epson/Gutenprint, Simple Scan, SANE scanner support
07A	VM Guest	VMware Tools (auto-detect when running inside VM)
07B	VM Host	virt-manager, QEMU/KVM, libvirt, SPICE agent
08	Security GUI	tshark (CLI), Zenmap, EtherApe, KeePassXC, OTPClient, metadata-cleaner, gnome-nettool, Catfish, GRSync
09	Development	git-gui, gitk, meld, dkms, build tools, crypto libs, Python3 pip, ShellCheck, strace
11	Utilities	Timeshift, Synaptic, Qalculate, CopyQ, wavemon, Font Manager, MenuLibre

External Packages (installed via hooks)

Always-on: LibreWolf, Tor Browser, VeraCrypt, Monero GUI, Session Desktop, VSCodium, Portmaster, GitKraken, Tabby

One-click optional (hooks 0013+): ExifCleaner, VLC, WaveTerm, Bluefish, Obsidian, Joplin, Termius, virt-manager stack

Dynamic Layer System

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

Package Categories Breakdown

Desktop GUI Package Categories

Category	Count	Signature Packages
XFCE Desktop Core	~85	xfce4, xfce4-goodies, thunar, lightdm, kitty, tilix, conky-all, geany
Network GUI Apps	6	remmina, filezilla, transmission-gtk, syncthing, onionshare, uget
Multimedia	6	mpv, vokoscreen-ng, gthumb, guvcview
Office Suite	5	libreoffice, atril, pdftk-java, gedit
Printing & Scanning	19	cups, hplip, printer-driver-gutenprint, simple-scan, sane-utils
VM Guest Tools	2	open-vm-tools, open-vm-tools-desktop
Virtualization Host	9	virt-manager, qemu-system-x86, libvirt-daemon-system
Security Tools GUI	11	tshark, zenmap, keepassxc, otpclient, metadata-cleaner, catfish
Development Tools	32	git-gui, meld, dkms, linux-headers-amd64, python3-pip, shellcheck
Extra Utilities	7	timeshift, synaptic, qalculate-gtk, copyq, font-manager
Accessibility	3	speech-dispatcher, onboard, orca
Terminal Security (inherited)	270	All terminal.list.chroot packages (networking, VPN, security, firmware)
AI & Intelligence	Optional	KAICS tools and kodachi-claw (anonymous agent runtime)

Supported Routing Protocols

Kodachi Desktop ships with 12+ routing protocols 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
Anti-Censorship	Shadowsocks (SOCKS5 + encryption), V2Ray (traffic obfuscation), Xray (enhanced V2Ray), Hysteria2 (high-performance for restrictive networks), Mieru (MITA - lightweight anti-censorship proxy)
Proxy Protocols	SOCKS5 (standard proxy), Dante (SOCKS server), HTTP/HTTPS (proxy support), Microsocks (lightweight SOCKS5 server)
Tor Integration	Redsocks (transparent Tor routing), SOCKS proxy configuration, TransPort routing, DNS over Tor, System-wide torrification (can run on top of any existing VPN service)
Multi-Layer	VPN + Tor (double encryption), protocol chaining for enhanced anonymity, traffic obfuscation layers

Protocol Documentation

For detailed protocol configuration and usage, see the routing-switch documentation.

Torrification Capability

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

Kodachi Desktop inherits the full terminal security stack and adds GUI-specific protections for desktop environments.

AppArmor mandatory access control, AIDE file integrity monitoring, auditd kernel auditing, usbguard device whitelisting, Firejail sandboxing with GUI (Firetools)

Tor routing (system-wide torrification), VPN integration (12+ protocols), DNS encryption (DNSCrypt), MAC address randomization, kill switch protection

Portmaster application-level firewall and monitor, UFW/GUFW graphical firewall management, nftables/iptables network filtering, per-application network rules

Metadata cleaning (mat2, metadata-cleaner), secure deletion (secure-delete, BleachBit, nwipe), encrypted containers (SiriKali, VeraCrypt), LUKS disk encryption

KeePassXC password manager, OTPClient TOTP/HOTP authenticator, Kleopatra GPG key management, fail2ban SSH brute-force protection

tshark packet capture (CLI), Zenmap network scanner, EtherApe traffic visualization, gnome-nettool diagnostics, DNS leak testing

Conky Desktop Monitor

Live Security Telemetry Rendered on Desktop

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.

5 Panels

22 Scripts

8 Cairo Gauges

7 Config Files

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

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 5 categories

Tor Circuits: Active circuit count via tor-switch

DNSCrypt Status: Encryption state via dns-switch

Firewall Rules: nftables active count

21 Metrics: Auth, VPN, MAC randomization, hostname spoofing, timezone obfuscation, swap encryption, kernel hardening, AppArmor, USBGuard, systemd health, package integrity, file permissions, network interfaces, connections, privilege escalation

CPU Frequency: Scaling governor state

Thermal Zones: CPU temp, GPU temp, disk temp

Fan Speeds: If supported by sensors

Load Average: 1min, 5min, 15min

Uptime: Precision to seconds

Logged Users: Active session count

Sparkline Graphs: Upload/download trends (60s windows)

Top Processes: Bandwidth consumers ranked by bytes sent/received

Connection States: ESTABLISHED, TIME_WAIT, CLOSE_WAIT counts

Kodachi Logo: Top-right corner overlay

13 AI Agents Detected: Claude Code, Ollama, OpenAI GPT, GitHub Copilot, Codex, TabNine, Kite, Codeium, Amazon CodeWhisperer, Replit Ghostwriter, JetBrains AI, Cursor, Continue

Per-Agent Stats: CPU % and memory consumption

Advanced Monitoring Features

Prime Number Refresh: 41s, 43s, 47s, 53s, 59s, 113s intervals prevent API collision

VPS Node Status: Pings configured servers, shows latency + packet loss

Crypto Prices: BTC, ETH, XMR, AZERO, Gold, Silver via privacy APIs

Version Alerts: Blink animation for outdated binaries (red = critical updates)

Lock Files: Prevent duplicate script execution (300s stale timeout)

Privacy DNS Ping: Cloudflare 1.1.1.1, Quad9 9.9.9.9, Mullvad 194.242.2.2 (zero Google)

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 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
Global Config	1 file	`config.rasi` — master Rofi configuration setting default theme, font, and display options

Kodachi Rofi Actions (keyboard-driven security menus)

Menu	Script	Purpose
Actions	`menu-actions.sh`	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 Matrix

Kodachi Desktop bundles 30+ firmware packages inherited from the terminal base, plus GPU drivers for desktop rendering.

Hardware Support Matrix

Hardware Type	Supported Chipsets & Manufacturers
WiFi	Intel (all generations), Broadcom (modern + legacy wl driver), Atheros/Qualcomm, Realtek, MediaTek, Marvell, TI, Atmel
Ethernet	Broadcom (bnx2, bnx2x), Cavium, Myricom, Netronome, QLogic, Realtek
Bluetooth	BlueZ firmware, miscellaneous nonfree firmware
GPU / Graphics	AMD (amdgpu), Intel (i915), NVIDIA (nouveau open-source driver)
Microcode	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.

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

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.

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)
Conky dashboard initialization (real-time monitoring)

AutoShield — Interactive Setup Wizard

Kodachi AutoShield launches automatically on first boot as a countdown-driven privacy hardening console for identity randomization, secure routing, DNS setup, and live verification.

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 Modes Live Telemetry Identity Compare Shield Meter

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.

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.

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).

Shows identity values before and after execution: Hostname, MAC address, Timezone, Security Score. Each value has a copy button for easy clipboard access.

Non-authenticated users can run Authenticate, Refresh Status, Recover Internet, and Enable DNSCrypt. The remaining identity and routing actions require successful Kodachi authentication first.

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.

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

8 countdown modes:
• 60 seconds - Quick automated setup
• 2 minutes - Balanced timer
• 5 minutes - Extended review time
• 10 minutes - Default timer for review and customization
• 1 hour - Long review window
• 3 hours - Extended staging window
• 6 hours - Delayed execution window
• Manual - No auto-execution, manual trigger only

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.

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.

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.

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 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 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 closes the AutoShield window. Use when you have already run the steps you need and want to exit 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 AutoShield. Unlocks restricted steps (identity randomization, VPN, torrification) without switching to the main dashboard. If the auth banner appears, you must authenticate before those steps can execute.

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.

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.

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 > Dash

Opens the main Kodachi Dashboard. Escape hatch to the full dashboard for operations AutoShield 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.

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.

Editions Comparison

Kodachi Editions

Feature	Terminal Server	Desktop XFCE	Kodachi OS
Desktop	Headless (CLI only)	XFCE 4	Custom
Base	Debian 13 (Trixie)	Debian 13 (Trixie)	Debian
ISO Size	~2.4GB	~5GB	~2.9GB
Binary Suite	19 core binaries + companion tools	Full suite (29 bundled binaries)	Full suite
Tauri Dashboard	No	Yes	Yes
Kodachi Claw	Yes	Yes	Yes
Conky Monitor	No	Yes (Lua-powered)	Yes
Browsers	CLI only (w3m)	LibreWolf + Tor Browser	Custom
Office Suite	No	LibreOffice (optional layer)	Yes
Dynamic Layers	No	10 optional layers	Limited
Installer	CLI/Calamares	Calamares GUI + GRUB Debian installer	Live ISO
Target Use	Servers, VPS, proxy gateways	Desktop workstations, daily use	Live USB, privacy-first
Status	Available	Available	Available

Use Case Examples

Example 1: Daily Privacy Workstation

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

curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-debug-collector.sh | sudo bash

Skip the menu and collect everything:

curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-debug-collector.sh | sudo bash -s -- --all

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.

Stay Updated

Check for release announcements and updates on SourceForge. For questions or feature requests, visit Discord Support.

Kodachi Desktop Debian XFCE

Kodachi Desktop XFCE Edition

Download & Installation First Release: 26 February 2026 9.0.1 | Desktop last updated 08 April 2026 - build #58

Download ISO

Direct Download

Browse All Files

Installation Methods

Login Credentials

Create Bootable USB

Why Kodachi Desktop

Privacy by Design

12+ Routing Protocols

DNSCrypt Auto-Config

MAC Randomization

VPN Kill Switch

System Hardening

AppArmor

AIDE

auditd

Firejail

Portmaster

Secure Boot

Binary Security Suite

health-control

tor-switch

dns-switch

routing-switch

integrity-check

permission-guard

Kodachi Dashboard

Four Modes. One Mission. Total Control.

Routing Guide

Gamified Security Ring

First-Boot Setup Wizard

Compact Command Center

Professional Workstation

Core Infrastructure Across All Modes

Mode Comparison Matrix

Connectivity Highlights

Essentials > Actions > Connection > VPNGate

Essentials > Actions > Network Recovery > Fix Internet Wizard

Lite Dashboard Recovery + VPNGate Shortcuts

Dashboard Hints & Tips

Top Status Bar > AI Chat Button

Top Status Bar > Clapperboard Icon

Top Status Bar > Compact Mode Icon

Top Status Bar > Auth Toggle

Top Status Bar > Mode Selector

Top Status Bar > Sparkles Icon

Service Panel Header > Grid / List Icon

Service Panel Header > Help Icon

Service / Logs Header > Swap Icon

Service / Logs Header > Collapse Icon

Top Status Bar > Draggable Chips

Essentials > Actions

Essentials > Actions > Connection > VPNGate

Essentials > Actions > Network Recovery > Fix Internet Wizard

Essentials > Hardening

Essentials > Passwords

Essentials > Tor

Essentials > DNS

Essentials > Workflows

Essentials > Library

Essentials > Emergency

Essentials > AI

Dashboard > Resources

Dashboard > Processes

Dashboard > Network

Dashboard > Firewall

Dashboard > Startup

Dashboard > Logs

Dashboard > Terminal Tools

Routing Switch routing-switch

Tor Switch tor-switch

DNS Switch dns-switch

DNS Leak dns-leak

Health Control health-control

Online Auth online-auth

IP Fetch ip-fetch

Online Info online-info-switch

Routing Switch `routing-switch`

Tor Switch `tor-switch`

DNS Switch `dns-switch`

DNS Leak `dns-leak`

Health Control `health-control`

Online Auth `online-auth`

IP Fetch `ip-fetch`

Online Info `online-info-switch`

Integrity Check `integrity-check`

Permission Guard `permission-guard`

Workflow Manager `workflow-manager`

Global Launcher `global-launcher`

Kodachi AI `kodachi-ai`

Deps Checker `deps-checker`