# Kodachi Desktop (Debian XFCE) — Full Documentation

> Source: https://www.kodachi.cloud/wiki/bina/desktop-debian.html
> Extracted: 2026-04-29

---

## Overview

Kodachi Desktop is a security-focused Debian 13 (Trixie) XFCE desktop distribution built for privacy, anonymity, and advanced network routing. It bundles 29 pre-installed binaries, a Tauri-based dashboard, Conky live telemetry, 12+ routing protocols, and an AI suite.

---

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

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

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

---

## Supported Routing Protocols

Kodachi Desktop ships with **12+ routing protocols** via the `routing-switch` binary.

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

### Torrification Capability
System-wide torrification 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.

```bash
sudo tor-switch torrify-system-nftables-dns
```

---

## Workflow Selection Guide (Anonymity Tiers)

| Tier | Chain | Anonymity | Speed | Best For |
| --- | --- | --- | --- | --- |
| **TIER 1** | Triple VPN + Tor (Workflows 01-03) | Ultra++ (6/6) | Slowest to Very Slow | Ultimate anonymity, state-level adversaries, whistleblowing |
| **TIER 2** | Double VPN + Tor (Workflows 04-08) | Ultra (5/5) | Slow to Moderate | Investigative journalism, activist operations |
| **TIER 3** | Single VPN + Double Tor (Workflows 09-11) | Very High (4.5/5) | Very Slow to Slow | .onion operations, dark web research |
| **TIER 4** | Double VPN without Tor (Workflows 12-14) | High (4/5) | Good to Very Good | Censorship bypass, DPI evasion |
| **TIER 5** | Single VPN + Tor (Workflows 15-17) | Moderate-High (3.5/5) | Moderate | Hostile network environments |
| **TIER 6** | Single VPN Only (Workflow 18) | Moderate (3/5) | Fast | Online banking, shopping, business email |

### Protocol-Specific Initial Setup Workflows

Execute with: `sudo workflow-manager run <profile-name>`

| Profile | Description |
| --- | --- |
| `initial_terminal_setup_openvpn_only` | OpenVPN connection setup |
| `initial_terminal_setup_wireguard_only` | WireGuard connection setup |
| `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 |
| `initial_terminal_setup_dante_only` | Dante SOCKS5 server |
| `initial_terminal_setup_mita_only` | Microsocks lightweight SOCKS5 |
| `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 |

---

## Security & Privacy Features

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

---

## Conky Desktop Monitor

Lua-powered desktop monitor with **5 panels**, **22 monitoring scripts**, **8 Cairo gauges**, and a shared Rust `conky-status` gateway.

### Panels & Stats
- **Signal Deck:** Top-center event-driven deck for anomalies
- **Cairo Gauges:** Upload, Download, CPU, Memory, Disk, Swap, Ping (dual-ring), Bandwidth
- **4×6 Binary Grid:** AUTH/VPN/TOR/DNS visual status
- **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 Security 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
- **Thermal/Fan/Load:** CPU temp, GPU temp, disk temp, fan speeds, load average, uptime
- **Sparkline Graphs:** Upload/download trends (60s windows)
- **Top Processes:** Bandwidth consumers ranked by bytes sent/received
- **13 AI Agents Detected:** Claude Code, Ollama, OpenAI GPT, GitHub Copilot, Codex, TabNine, Kite, Codeium, Amazon CodeWhisperer, Replit Ghostwriter, JetBrains AI, Cursor, Continue

### Privacy Screenshot Mode
The Lite Dashboard diagnostics menu includes **Conky Mask Enable**, **Conky Mask Disable**, and **Conky Mask Status**. These mask sensitive fields such as IP, MAC, and country data for safe screenshots.

---

## Rofi Menu System

Pre-configured with **202 theme and configuration files** covering application launchers, power menus, system applets, and color schemes.

| Component | Count | Description |
| --- | --- | --- |
| **Launcher Themes** | 7 types | Application launcher styles |
| **Power Menus** | 6 types | Shutdown, reboot, lock, suspend, logout |
| **Applets** | 5 types | Brightness, volume, screenshot, network, battery |
| **Color Schemes** | 16 palettes | Pre-built `.rasi` color themes |
| **Theme Files** | 162 `.rasi` | Complete theme definitions |
| **Scripts** | 23 `.sh` | Launcher and power menu runner scripts |
| **Images** | 15 assets | Background images and icons |
| **Global Config** | 1 file | `config.rasi` — master configuration |

### Kodachi Rofi Actions
- **Actions** (`menu-actions.sh`): Primary dispatcher
- **Favorites** (`menu-favorites.sh`): Quick-launch frequently used tools
- **Network** (`menu-network.sh`): VPN connect/disconnect, Tor toggle, DNS switching, routing mode
- **Services** (`menu-services.sh`): Start, stop, and check system services
- **Utilities** (`menu-utilities.sh`): System cleanup, MAC randomization, hostname change, panic triggers

All scripts are installed to `/usr/local/lib/kodachi-rofi/` and invoked via `kodachi-rofi-actions`.

---

## Hardware Support Matrix

| Hardware Type | Supported Chipsets & Manufacturers |
| --- | --- |
| **WiFi** | Intel, Broadcom, 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 b43 and b43legacy firmware is pre-installed** in the ISO at `/lib/firmware/b43/` and `/lib/firmware/b43legacy/`.

---

## Desktop Customization

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

### 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 (Advanced options & fallback modes…)
- Normal GUI installer
- `Install Kodachi (Text + Full Disk Encryption, Boot-Nuke Compatible)`
- `Install Kodachi (Unattended + Full Disk Encryption, Boot-Nuke Compatible)`

---

## Kodachi AutoShield

Interactive Setup Wizard that launches automatically on first boot.

### What Happens on First Boot
1. **LightDM Login** — `kodachi` / `Security4All`
2. **XFCE Desktop** — Dark-themed XFCE desktop loads
3. **Conky Dashboard** — Real-time system monitor appears
4. **Kodachi Dashboard** — Welcome screen with terms, dashboard mode selection, optional privacy settings
5. **Automatic Setup** — DNSCrypt auto-configuration, binary verification, online authentication, system status collection

### 9 Configurable Security Steps

| Step | Command | Default | Before/After Tracking |
| --- | --- | --- | --- |
| **Authenticate with Kodachi Services** | `online-auth authenticate --relogin` | Enabled | Auth status |
| **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 |
| **Recover Internet Connectivity** | `health-control recover-internet` | Enabled | Network state |
| **Quick Connect WireGuard** | `routing-switch connect wireguard` | Enabled | VPN status |
| **Torrify System + DNS** | `tor-switch torrify-system-nftables-dns` | Disabled | Tor status |
| **Refresh System Status** | Fetches current IP, geolocation, auth, VPN, Tor, DNS status | Enabled | All current system values |

### Shield Strength Protection Levels

| Level | Steps Enabled | Visual Effect | Description |
| --- | --- | --- | --- |
| **Low** | 0-2 steps | Red pulsing bar | Minimal protection |
| **Medium** | 3-4 steps | Yellow pulsing bar | Partial protection |
| **High** | 5-6 steps | Green pulsing bar | Strong protection |
| **Maximum** | 7+ steps | Bright green pulsing bar | Ultimate protection |

### 8 Countdown Modes
- 60 seconds, 2 minutes, 5 minutes, 10 minutes (default), 1 hour, 3 hours, 6 hours, Manual

### Key AutoShield Footer Buttons
- **Execute** — Run all enabled steps
- **Skip** — Skip remaining steps
- **Reset** — Restore factory defaults
- **Stop** — Halt execution after current step
- **Restart** — Restart countdown timer
- **Dash** — Open main Kodachi Dashboard
- **K Browser** — Launch LibreWolf (privacy hardened)
- **O Browser** — Launch Oniux Browser (Tor-isolated)
- **O Term** — Launch Oniux Terminal (Tor-isolated)
- **Tor** — Launch Tor Browser
- **Rise** — Launch RiseVPN

### VPN + Tor Layering
To run VPN and Tor simultaneously, let AutoShield connect WireGuard (or any VPN) first. After VPN is active, manually run **Torrify System + DNS**. This routes traffic through VPN first, then Tor.

---

## Editions Comparison

| 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 | 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 entries | Live ISO |
| **Target Use** | Servers, VPS, proxy gateways | Desktop workstations, daily use | Live USB, privacy-first |
| **Status** | Available | Available | Available |

---

## Use Case Examples

1. **Daily Privacy Workstation** — LibreWolf for browsing, LibreOffice for documents, Tor Browser for sensitive research. All traffic through VPN + Tor.
2. **Secure Development Machine** — Enable Development layer. Write code with Firejail sandboxing, GPG-signed commits via Kleopatra.
3. **Multimedia & Content Creation** — Activate Multimedia layer for vokoscreen-ng and mpv.
4. **Network Security Audit** — Enable Security GUI layer for tshark, Zenmap, and EtherApe.
5. **Air-Gapped Secure Computing** — Boot in Maximum Privacy mode (entirely in RAM). Use KeePassXC, SiriKali, and BleachBit.
6. **Virtual Machine Testing Lab** — Enable Virtualization Host layer for virt-manager and QEMU/KVM for nested security testing.

---

## Debug Collector

If you encounter issues, the **Debug Collector** gathers system diagnostics into a single zip file.

```bash
# Interactive category menu
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-debug-collector.sh | sudo bash

# Skip menu and collect everything
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-debug-collector.sh | sudo bash -s -- --all
```

Output is saved to `~/Desktop/kodachi-debug-*.zip`.

**Privacy note:** Does NOT capture IP addresses, passwords, browsing data, or personal files. WiFi credentials and MAC addresses are automatically redacted.

---

## Stay Updated

- **Downloads:** [SourceForge](https://sourceforge.net/projects/linuxkodachi/files/kodachi-desktop/)
- **Support:** [Discord](https://discord.gg/KEFErEx)
- **Contact:** [Contact Form](https://www.kodachi.cloud/wiki/bina/support.html)

---

*Documentation extracted from https://www.kodachi.cloud/wiki/bina/desktop-debian.html*