A minimal, terminal-only live ISO based on Debian 13 (Trixie) crafted for two critical missions: bulletproof testing of the full Kodachi toolchain and operating as a dedicated SOCKS proxy gateway for your network.
Built for power users, hardened servers, and elegant headless deployments.
Production HardenedMulti-ProtocolProxy-ReadyAI-PoweredHardware Optimized
Download & Install
Download & Installation First Release: 30 October 2025 9.8.4 Queen | Terminal last updated 26 June 2026 - build #182
Download ISO
Direct Download
Latest
Download the latest Kodachi Terminal Server ISO directly. One-click access to the current release.
linux-kodachi-terminal-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 on dedicated hardware for maximum performance as proxy server
Virtual Machine
Run in VMware/VirtualBox/QEMU for isolated testing environment
Live USB
Boot from USB drive - no installation, portable, leaves no traces
Persistent Storage
Enable persistence for configuration retention across reboots
Login Credentials
Username:kodachi
Password:Security4All
These are the live/default kodachi account credentials. root login is disabled and does not use this password.
# Find USB device
lsblk
# Write ISO to USB (replace /dev/sdX with your USB device)
sudo dd if=linux-kodachi-terminal-9.0.1-amd64.iso of=/dev/sdX bs=4M status=progress oflag=sync
macOS dd
# Find disk identifier
diskutil list
# Unmount disk
diskutil unmountDisk /dev/diskN
# Write ISO
sudo dd if=linux-kodachi-terminal-9.0.1-amd64.iso of=/dev/rdiskN bs=4m
WARNING: dd will overwrite all data on the target drive
Double-check the device identifier before running the dd command. Using the wrong device will permanently erase that drive's contents.
conky-status (Conky details, legacy conky-details naming) ships in the unified binary pack, but its Conky desktop display is only used on Desktop XFCE builds (the terminal edition has no GUI)
Interface
Terminal-only (no GUI)
Boot Support
BIOS + UEFI compatible
Login Credentials
Username: kodachi / Password: Security4All
Sudo Access
Passwordless sudo enabled
Pre-Installed Binaries
Pre-Installed Kodachi Binaries
All 28 terminal binaries (the 20 core binaries below plus the 8 KAICS ai-* binaries) are pre-installed at /opt/kodachi/dashboard/hooks/. Launch the toolkit instantly without additional setup.
Desktop add-on: the Rust conky-status telemetry gateway (Conky details binary, legacy conky-details naming) is included in the 20-binary core set above, but its Conky desktop display is only active on Desktop XFCE builds, as the terminal edition has no GUI to render it.
Runtime crypto libs and Python tooling (e.g. libssl3, python3-pip, shellcheck). The matching -dev headers (libssl-dev, linux-headers-amd64, etc.) are excluded: they are compile-time only and not needed at runtime.
KAICS tools (ai-cmd, ai-gateway, and 6 related binaries) are pre-installed as part of the 28-binary pack
Base System (total ISO)
1603
Debian core utilities, libraries, and runtime dependencies from the ISO manifest
Dependency installer additions: the package list above covers entries declared in terminal.list.chroot / live.list.chroot. The build also runs kodachi-deps-install.sh from its chroot hook (9999-zzz-kodachi-install) to guarantee the privacy and hardening stack is present even when a package is not in those lists. The following reach the ISO through the installer script rather than the package list:
On a standalone (non-live) Debian system you can install the same dependency stack yourself with sudo bash kodachi-deps-install.sh; the matching Kodachi binaries are installed by kodachi-binary-install.sh, and kodachi-debug-collector.sh gathers diagnostics for support without installing anything.
Routing Protocols
Supported Routing Protocols
Kodachi Terminal Server ships with 11 auto-scored routing protocols (plus xray-vmess as a legacy fallback) via the routing-switch binary, covering everything from battle-tested VPNs to advanced censorship-resistant transports.
Routing Protocol Coverage
Category
Protocols & Features
VPN Protocols
OpenVPN (industry-standard, AES encryption), WireGuard (modern, ChaCha20 encryption), with kill switch and DNS leak protection
Redsocks (transparent Tor routing), SOCKS proxy configuration, TransPort routing, DNS over Tor, System-wide torrification (can run on top of any existing VPN service: WireGuard, OpenVPN, Hysteria2, Shadowsocks, V2Ray, Xray, Mieru)
Multi-Layer
VPN + Tor (double encryption), protocol chaining for enhanced anonymity, traffic obfuscation layers
Kodachi Terminal supports system-wide torrification that can run on top of any existing VPN service. This means you can 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 (preferred) or sudo tor-switch torrify-system-iptables-dns to torrify your entire system regardless of your underlying VPN connection. To disable, use sudo tor-switch detorrify-system-nftables or sudo tor-switch detorrify-system-iptables.
Security Models
Security Models & Layered Anonymity
Kodachi Terminal includes 96 pre-built security workflows and supports unlimited custom workflows via the workflow-manager binary. Below are 18 example workflows organized by anonymity levels with diverse protocol coverage (WireGuard, OpenVPN, Shadowsocks, Hysteria2, V2Ray, Xray, Mita). Workflows 1-3 (Triple VPN + Tor) provide maximum anonymity for extreme threat models. Workflows 4-8 (Double VPN + Tor) offer ultra anonymity with host+guest configurations. Workflows 9-11 (Single VPN + Double Tor) provide very high anonymity. Workflows 12-18 balance security with performance for various use cases. All profiles are located in /opt/kodachi/dashboard/hooks/config/profiles/. Users can create, modify, and chain workflows using workflow-manager to build custom security configurations.
initial_terminal_setup_wireguard_torrify - WireGuard + Tor torrification
initial_terminal_setup_auth_torrify_only - Authentication + Tor torrification
Execute with:sudo workflow-manager run <profile-name>
Workflow Selection Guide - Organized by Anonymity Tiers
TIER 1: Maximum Anonymity - Triple VPN + Tor (Workflows 01-03)
- Anonymity Level: Ultra++ (6/6) - Triple VPN protection with Tor torrification
- Best for: Ultimate anonymity, extreme threat models, state-level adversaries, whistleblowing, maximum deniability
- Configuration: Router VPN → Host VPN (Mullvad/ProtonVPN/NordVPN) → Kodachi VPN (WireGuard/OpenVPN/Shadowsocks) → Torrified System → Tor DNS
- Speed: Slowest to Very Slow
TIER 2: Ultra Anonymity - Double VPN + Tor (Workflows 04-08)
- Anonymity Level: Ultra (5/5) - Double VPN with Tor torrification
- Best for: Different VPN providers, avoiding single-point surveillance, investigative journalism, activist operations, censorship bypass with maximum protection
- Configuration: Normal Router → Host VPN (Mullvad/ProtonVPN/NordVPN/ExpressVPN) → Kodachi VPN (OpenVPN/Shadowsocks/V2Ray/Hysteria2) → Torrified System → Tor DNS
- Speed: Slow to Moderate
TIER 3: Very High Anonymity - Single VPN + Double Tor (Workflows 09-11)
- Anonymity Level: Very High (4.5/5) - Double Tor circuits or Router + Guest VPN + Tor
- Best for: Extreme anonymity requirements, .onion operations, dark web research, sensitive communications, maximum deniability
- Configuration: Kodachi VPN (Xray/WireGuard) → Torrified → Double Tor Circuits OR Router VPN → Kodachi VPN → Torrified System
- Speed: Very Slow to Slow
TIER 4: High Anonymity - Double VPN without Tor (Workflows 12-14)
- Anonymity Level: High (4/5) - Double VPN layer
- Best for: Censorship bypass, DPI evasion, advanced anti-detection, high-performance with strong privacy
- Configuration: Normal Router → Host VPN (Mullvad/ProtonVPN/ExpressVPN) → Kodachi VPN (Shadowsocks/Hysteria2/Xray-VLESS-Reality) → DNSCrypt
- Speed: Good to Very Good
TIER 5: Moderate-High Anonymity - Single VPN + Tor (Workflows 15-17)
- Anonymity Level: Moderate-High (3.5/5) - Single VPN with Tor
- Best for: Hostile network environments, general privacy, anonymous browsing, daily privacy operations, secure communications
- Configuration: Kodachi VPN (Hysteria2/V2Ray/Shadowsocks) → Torrified System → Tor DNS
- Speed: Moderate
TIER 6: Moderate Anonymity - Single VPN Only (Workflow 18)
- Anonymity Level: Moderate (3/5) - Single VPN with encrypted DNS
- Best for: Online banking, shopping, business email, general secure browsing, fast performance requirements
- Configuration: Kodachi VPN (OpenVPN) → DNSCrypt
- Speed: Fast
Create Custom Workflows using workflow-manager for: Multi-protocol chains, adaptive failover, custom threat models, automated security responses, and specialized use cases.
NOT Recommended: Tor → VPN
Avoid Configuration: Your Computer → Tor → VPN → Internet
This configuration is widely discouraged; it blocks .onion access, lets the guard see your real IP, makes Tor usage detectable, degrades performance, and shifts trust to the VPN.
Why this is dangerous: Entry nodes see your real IP • ISP detects Tor usage • NO access to .onion sites • Severely degraded performance • VPN provider can see your activity
Based on Privacy Guides 2025 recommendations, Tor Project official documentation, and Kodachi security research. These workflows represent comprehensive threat modeling from maximum anonymity to secure financial operations.
Hardware Support
Hardware Support Matrix
Kodachi Terminal Server bundles 30+ firmware packages to deliver broad WiFi, Ethernet, Bluetooth, GPU, and microcode coverage out of the box.
Realtek (in-kernel driver, no firmware needed), plus standard kernel-supported chipsets (Intel e1000/igb/ixgbe, Atheros). Enterprise NIC firmware (bnx2/x, Cavium, Myricom, Netronome, QLogic) intentionally excluded per 24 April 2026 hardware audit (not present on desktop/laptop/VM targets)
Bluetooth
BlueZ firmware, miscellaneous nonfree firmware
GPU / Graphics
AMD (amdgpu for terminal console), Intel (microcode)
Microcode
Intel CPU microcode updates, AMD CPU microcode updates
Broadcom Wireless Support - Pre-Installed
Broadcom b43 and b43legacy firmware is pre-installed in the ISO at /lib/firmware/b43/ and /lib/firmware/b43legacy/.
Supported chipsets:
b43legacy: BCM4301, BCM4303, BCM4306/2 (very old cards)
broadcom-sta-dkms (wl proprietary driver, alternative for some cards)
b43-fwcutter tool (if you need to extract different firmware versions)
No post-boot installation required - firmware is ready to use immediately.
SOCKS Proxy Setup
SOCKS Proxy Server Setup (Primary Use Case)
One of Kodachi Terminal's primary use cases is running as a dedicated SOCKS proxy server for your entire network. This allows all devices (phones, tablets, computers) to route traffic through a single anonymized gateway.
Step-by-Step Server Setup
1. Boot Kodachi Terminal Server on dedicated hardware or VM
These are the live/default kodachi account credentials. root login is disabled and does not use this password.
2. Configure network routing
sudorouting-switchconnectwireguard# Connect to VPNsudotor-switchtorrify-system-nftables-dns# Torrify system + Tor DNSsudodns-switchswitch--namesdnscrypt-quad9# Privacy-focused DNS
3. Start SOCKS proxy server (choose one)
Option A: V2Ray SOCKS5 proxy (recommended for performance)
microsocks-i0.0.0.0-p30050# Listen on all interfaces, port 30050
Option C: Dante SOCKS server (enterprise-grade)
sudoaptinstalldante-server
sudosystemctlstartdanted
# Configure /etc/danted.conf for your network
4. Configure client devices
Point all devices on your network to use:
- SOCKS5 Server:<Kodachi-Terminal-Server-IP>:30050 (or your chosen port)
- Protocol: SOCKS5
5. Verify proxy is working
sudoip-fetchfetch# Check exit IPhealth-controlnet-check# Verify no leakssudodns-leaktest# DNS leak test
Managing the Proxy Server
# Monitor active proxy connectionssudonetstat-tulpn|grepmicrosocks
# Configure firewall to restrict proxy access to trusted IPssudoiptables-AINPUT-ptcp--dport30050-sTRUSTED_IP-jACCEPT
sudoiptables-AINPUT-ptcp--dport30050-jDROP
Use Cases
Use Case Examples
V2Ray Proxy Server for Network
Boot Kodachi Terminal Server on old laptop → Connect to VPN → Start V2Ray SOCKS5 server → Configure all home devices to use proxy → Entire household anonymized
VMware Testing Environment
Run Kodachi Terminal Server in VMware Workstation/Fusion → Test all 28 pre-installed terminal binaries safely → Snapshot before testing → Roll back after experiments → No impact on host system
Dedicated Proxy Server Hardware
Old desktop/laptop → Boot Kodachi Terminal Server → Enable persistent storage → Configure routing protocols → Run 24/7 as network proxy gateway → Centralized anonymity for all devices
Internet Café/Public Computer
Boot from USB → No installation required → Use Kodachi binaries for secure browsing → Shut down → No traces left on host machine
Travel & Hotels
Boot Kodachi Terminal Server on travel laptop → Connect to hotel WiFi → Enable VPN + Tor → Access sensitive accounts securely → Bypass local censorship/monitoring
Corporate/Educational Testing
Security researchers → Test Kodachi binaries in isolated VM → Learn CLI commands → Verify routing configurations → Safe environment for experimentation
Boot Menu Overview
Kodachi Terminal Server groups every boot entry by security tier so you can pick the right hardening profile without hunting through every submenu. Use the comparison table for a quick overview, then drop into the guidance below to narrow the choice.
Boot Speed Tip
The first (top) GRUB entry is Kodachi 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.
If you want lower RAM usage and faster startup, select the normal Kodachi Live mode from the boot menu.
Some commands or services may fail under stricter hardening profiles; if something does not work, reboot and switch to a less restrictive profile.
IPv6 Defaults Per Boot Tier
Starting with Kodachi 9.0.1, the IPv6 kernel stack is enabled by default on Tier 1-3 entries and on the fallback/compatibility entries. This means the Dashboard IPv6 control (and health-control ipv6-disable / ipv6-enable) can flip IPv6 on or off at runtime via sysctl, with no reboot required.
Only three top-tier hardening entries keep the historical ipv6.disable=1 kernel flag:
M · Kodachi Maximum Privacy (Tier 4)
F · Kodachi Forensics Mode (Tier 5)
H · Kodachi Full Hardening (Tier 5)
On those three entries the IPv6 stack is never initialized, /proc/sys/net/ipv6/ is absent, and the Dashboard cannot bring IPv6 back without rebooting into a lower tier. Pick a Tier 1-3 entry if you need runtime IPv6 control.
H · Kodachi Full Hardening: every mitigation enabled for hostile environments.
F · Kodachi Forensics Mode: boots fully in RAM so you can analyze target machines without modifying their disks, and your session leaves no trace behind. Does not wipe memory on shutdown by default (use health-control ram-wipe-enable or the Dashboard to enable it).
Tier 4: Secure Boot & privacy
S · Kodachi Secure Boot Mode: signed modules and lockdown policies for UEFI Secure Boot.
M · Kodachi Maximum Privacy: RAM-only session with debug hooks disabled and memory wiped on shutdown.
Tier 3: Hardened persistence choices
C · Kodachi CPU Hardened: prioritizes speculative-execution mitigations on legacy or cloud hardware.
E · Encrypted Persistence: keeps long-term data in a LUKS volume without sacrificing daily usability.
Tier 2 / Tier 1: Everyday & disposable boots
P · Kodachi Persistent: saves changes on trusted hardware without the overhead of encryption.
L · Kodachi Live: fastest throwaway session for diagnostics, demos, or compatibility checks.
Advanced Menu Highlights
Open Advanced options & fallback modes... at the boot screen to pick from:
Security add-ons · DMA Protection, Hardened Malloc, Full RAM mode, and Performance Balanced profiles.
DNSCrypt Auto-Configuration - Enables encrypted DNS on first run (creates marker file)
Online Authentication - Authenticates user session with Kodachi services for premium features and account verification
System Status Collection - Fetches IP, geolocation, network info, security score
Interactive Menu Display - Multi-level menu with 13 main options and 4 submenus (25+ configuration choices)
Auto-Refresh System - Updates all information every 10 minutes automatically
Note: 28 binaries (20 core + 8 KAICS AI) are available in the hooks directory of the base terminal ISO. Full deployment verification via global-launcher verify checks symlink integrity.
System Status Dashboard
AutoShield displays comprehensive real-time status information with auto-refresh every 10 minutes:
Category
Information Displayed
System Type
Live ISO / Installed-Encrypted / Installed-Unencrypted
Connected protocol (WireGuard, OpenVPN, etc.) or "No VPN"
Torrification
Active Tor routing or Direct connection
DNS Config
DNSCrypt, Tor DNS, or Direct DNS servers
Geolocation
Current IP address, Country, City
System Info
Hostname, MAC address, Timezone
Crypto Prices
BTC, ETH, XMR, AZERO current USD prices (fetched from VPS)
Latest News
Security and privacy news headlines (fetched from VPS)
Status Indicators
[GDeploy:+/-/N/A] Global deployment | [Auth:+/-/⊘] Authentication | [TSync:+/~/⊘] Time sync | [SDNS:*] DNS status | [Net:+] Network | [PermG:+/-] Permission guard
Offline Mode: If internet connectivity is not available, AutoShield operates in offline mode. Online data (crypto prices, news, authentication) will show placeholder values, and local DNS configuration will be used. All local features remain fully functional.
Security Scoring Explained
You Do NOT Need a High Score to Be Secure
A score of 60-75 (Fair to Good) is perfectly adequate for daily use. The higher you push the score, the more things may stop working for normal browsing and daily tasks.
Features like disabling WiFi, blocking USB, killing Bluetooth, and full kernel hardening are designed for HIGH-THREAT scenarios (journalists in hostile countries, whistleblowers, one-time sensitive operations). For a daily driver, you want MODERATE security that balances privacy, security, and stability.
Combining aggressive features like Secure Boot + LUKS + full hardening + Tor can cause breakage: services may fail, hardware may not be detected, boot times increase significantly. A score of 50-65 with VPN + DNSCrypt + firewall active is already far more secure than 99% of operating systems. Only push to 90+ if you are protecting something truly critical and accept that convenience will suffer.
How the Scoring Works
The security score is calculated by sudo health-control security-score on a 100-point scale across 7 categories. The system is context-adaptive: headless systems skip Bluetooth/webcam checks, WiFi-only systems skip WiFi checks, live-ISO sessions skip disk encryption / swap encryption / auto-updates / backup / encrypted-container checks, BIOS-only machines skip Secure Boot, and systems without swap skip swap encryption. Excluded checks drop out of the maximum rather than counting as failures, so the displayed total may read e.g. 57 / 82 instead of 57 / 100 (that is intentional and reflects what your hardware can actually achieve). VPN/proxy and Tor are scored independently in Privacy & Anonymity, so running both layers them additively (++).
Category
Maximum Points
Scoring Criteria
1. Privacy & Anonymity
25 points
Tor + Torrification (8): Tor active AND system torrified
All hardening enabled, Tor + VPN, USB blocked, WiFi/BT off, full kernel hardening
Minimal
50
Testing, compatibility verification
Firewall active, auto-login off, no VPN/Tor, basic DNS only
Command: Run sudo health-control security-score to see your current score and detailed breakdown. The score is percentage-based: (earned points / applicable maximum) × 100.
Pro Tip: The security score is displayed in the Terminal welcome status dashboard above (row 2). It automatically updates every 10 minutes along with other system metrics.
Interactive Menu System
AutoShield presents a multi-level menu system with 13 main options organized into 3 sections, plus 4 interactive submenus:
Clear all firewall rules → Reset to default policy → Clean state
[6] Reboot System
Executes: sudo reboot
Immediate system reboot
[7] Shutdown System
Executes: sudo shutdown -h now
Immediate system shutdown
[8] Exit (skip to shell)
Exit the welcome menu and access bash shell. Type kodachi to return to menu
[0] Back to Main Menu
Return to the main menu
Menu Navigation
Post-Workflow Execution:
After executing any workflow, you'll see navigation options:
- [Enter] - Refresh all system data and display menu (recommended - updates IP, security score, network status)
- [s] - Skip refresh and display menu immediately (faster but uses cached data)
- [Ctrl+C] - Exit to shell
Submenu Navigation:
- Select option number (1-8) to execute that option
- Press [0] to return to the previous menu
- All menu selections are immediate (no confirmation required)
Auto-Refresh System:
- AutoShield automatically refreshes all data every 10 minutes
- Refreshes: IP geolocation, network status, security score, crypto prices, news headlines
- Timeout is configurable by editing line 125 in /etc/profile.d/kodachi-autoshield.sh
DNS Auto-Configuration
First Boot Setup:
On first login, AutoShield automatically:
1. Detects if DNSCrypt has been configured (checks for marker file results/dns-configured in hooks directory)
2. If not found, initiates DNSCrypt auto-configuration
3. Attempts configuration up to 3 times with 5-second delays between attempts
4. Creates marker file results/dns-configured to prevent reconfiguration on subsequent logins
5. Auto-recovery from systemd-resolved conflicts (detects hijacking and restores DNSCrypt)
Force Reconfiguration:
# Force DNSCrypt setup even if marker existskodachi-autoshield.sh--force-dns-setup
DNSCrypt Verification:
The script continuously verifies:
- DNSCrypt service is running
- DNSCrypt is the active DNS resolver (not hijacked by systemd-resolved)
- DNS queries are encrypted
- Fallback to direct DNS if DNSCrypt fails after authentication errors
System Initialization
Binary Deployment:
AutoShield automatically:
1. Detects hooks directory location (installed system vs. live session)
2. Searches multiple paths: /opt/kodachi/dashboard/hooks/, local directories
3. Verifies the core Kodachi binaries are present and executable
4. Calls global-launcher verify for comprehensive deployment validation
5. Falls back gracefully if binaries are not found
Network Initialization:
1. Waits 5 seconds for network interfaces to initialize
2. Checks internet connectivity via health-control net-check --domain-only
3. If online: Attempts authentication with online-auth check-login
4. If offline: Operates in offline mode (skips authentication, online data fetching)
GRUB Theme Management (Installed Systems Only):
1. Checks if system is installed (not live ISO)
2. Verifies /boot/grub/live-theme/theme.txt exists
3. If missing, automatically runs /usr/local/bin/kodachi-apply-grub-theme
4. Silent operation on live sessions
Configuration Options
Command-Line Flags:
# Force DNSCrypt reconfigurationkodachi-autoshield.sh--force-dns-setup
Environment Variables:
# Skip AutoShield permanentlyexportKODACHI_SKIP_WELCOME=1# Add to ~/.bashrc for persistent skipecho'export KODACHI_SKIP_WELCOME=1'>>~/.bashrc
Auto-Refresh Timeout:
Edit line 125 in /etc/profile.d/kodachi-autoshield.sh:
AUTO_REFRESH_TIMEOUT=600# Default: 10 minutes (600 seconds)# Change to desired value (e.g., 300 for 5 minutes, 1200 for 20 minutes)
Installation Location:
AutoShield is installed at:
/etc/profile.d/kodachi-autoshield.sh
It auto-runs on every interactive shell login.
Manual Command Usage
After exiting the menu (System Options → [8] Exit), run commands manually:
# Explore all available commands with -e flaghealth-control-e# 50+ health control commandsrouting-switch-e# All routing and protocol commandsworkflow-managerlist# List all 96 workflow profilestor-switch-e# Tor management commandsdns-switch-e# DNS configuration commandscd/opt/kodachi/dashboard/hooks&&./global-launcher-e# Binary deployment commandsonline-auth-e# Authentication commandsintegrity-check-e# System verification commandsdns-leak-e# DNS leak detection commandspermission-guard-e# Permission management commandslogs-hook-e# Logging system commandsdeps-checker-e# Dependency checking commandsonline-info-switch-e# Online information commands# AI & Intelligence commands (KAICS - pre-installed)ai-cmd-e# Natural language command interfaceai-gateway-e# Agent-safe command gateway and policy firewallai-trainer-e# ML model training and validationai-learner-e# Learning orchestration and analysisai-admin-e# Database management and diagnosticsai-discovery-e# Binary watcher and auto-indexerai-scheduler-e# Cron-based task schedulerai-monitor-e# Proactive system monitoring# Quick status checkshealth-controlsecurity-score# Comprehensive security analysis (0-100)ip-fetch--json# Current IP and geolocation (JSON format)dns-leaktest# DNS leak detectionrouting-switchstatus# Network connection statustor-switchwhich-is-active# Active Tor configurationdns-switchstatus# Current DNS configuration# AI-powered operations (natural language interface)ai-cmdquery"check my network"# Natural language → command executionai-cmdinteractive# Start conversational AI sessionai-cmdquery"test dns leaks"--engineonnx# Use ONNX semantic modelai-cmdquery"analyze security"--enginemistral# Use local Mistral.rs GGUF modelai-cmdquery"check all services"--enginegenai# Use Ollama local providerai-cmdquery"analyze threats"--engineclaude# Use Claude CLIai-cmdtiers--json# Show available AI tiers and statusai-cmdtools--json# List callable AI toolsai-monitorstatus# Proactive monitoring statusai-monitorsuggestions# AI-generated security suggestions# ai-gateway machine/agent integrationai-gatewaysearch"tor status"--limit1--json|jq'.data.results[0].invocation'ai-gatewayruntor-switch--commandtor-status--dry-run--json
ai-gatewayrunip-fetch--commandfetch--args-json'{}'--dry-run--json
ai-gatewaycapabilities--agent-idanonymous--json
# Trusted agent example (token + trusted batch mode)KODACHI_TRUSTED_BATCH_MODE=trueKODACHI_AGENT_TOKEN_NULLCLAW=your_token\ai-gatewayrun--agent-idnullclaw--agent-tokenyour_token\--batch-json'[{"service":"tor-switch","command":"tor-status","dry_run":true}]'--json
# Dangerous command policy behaviorai-gatewayrunhealth-control--commandwipe-logs--dry-run--json
ai-gatewayrunhealth-control--commandwipe-logs--confirm"I understand"--json
# Network operations (commands used by submenus)dns-switchrandom# Set random reputable DNS serversdns-switchfallback# Set fallback DNS serverstor-switchrestart-all-instances# Restart all Tor instancestor-switchlist-instances-with-ip# List Tor IPs and countriestor-switchflush-iptables# Flush iptables firewall rulestor-switchflush-nftables# Flush nftables firewall rulesintegrity-checkcheck-all# Full system integrity verificationonline-info-switchreleases# Check latest Kodachi releases# Start SOCKS5 proxy serverrouting-switchmicrosocks-enable-uUSERNAME-pPASSWORD
Running Custom Workflows
Execute any of the 96 pre-built profiles directly:
# List all available workflows (96 profiles)workflow-managerlist
# Run specific VPN protocol workflowssudoworkflow-managerruninitial_terminal_setup_wireguard_only
sudoworkflow-managerruninitial_terminal_setup_openvpn_only
sudoworkflow-managerruninitial_terminal_setup_v2ray_only
sudoworkflow-managerruninitial_terminal_setup_xray_vless_reality_only
sudoworkflow-managerruninitial_terminal_setup_shadowsocks_only
sudoworkflow-managerruninitial_terminal_setup_hysteria2_only
sudoworkflow-managerruninitial_terminal_setup_dante_only
sudoworkflow-managerruninitial_terminal_setup_mita_only
# Run Tor/Torrification workflowssudoworkflow-managerruntorrify-balance-nftables-roundrobin
sudoworkflow-managerruntorrify-balance-nftables-consistent
sudoworkflow-managerruntorrify-balance-nftables-weighted
sudoworkflow-managerruninitial_terminal_setup_tor_only
sudoworkflow-managerruninitial_terminal_setup_auth_torrify_only
# Run DNS workflowssudoworkflow-managerrundns-dnscrypt-enable
sudoworkflow-managerruntor-dns-nftables-full
# Run system/recovery workflowssudoworkflow-managerrunrouting-disconnect-clean
sudoworkflow-managerrundetorrify-complete-verify
sudoworkflow-managerrunrecovery-master-complete
# Create custom workflowworkflow-managercreatemy-custom-workflow
Workflow Profiles Accessible from Menu:
The welcome menu provides access to 25+ specific workflows. All menu options execute workflows via workflow-manager run <profile_id>. Use workflow-manager list to see the complete list of 96 available profiles.
Bypassing AutoShield
To skip the interactive menu on login:
# Set environment variable before loginexportKODACHI_SKIP_WELCOME=1# Or add to ~/.bashrc to skip permanentlyecho'export KODACHI_SKIP_WELCOME=1'>>~/.bashrc
# Skip just onceKODACHI_SKIP_WELCOME=1bash
Re-Running AutoShield
To manually trigger AutoShield:
# Source AutoShield directlysource/etc/profile.d/kodachi-autoshield.sh
# Or type the shortcut command (if configured)kodachi
# With force DNS reconfigurationkodachi-autoshield.sh--force-dns-setup
VM & Boot Methods
VM and Boot Methods
VMware Workstation/Fusion
- 4GB+ RAM recommended
- 20GB+ disk (if enabling persistence)
- Network adapter: NAT or Bridged
- Boot from ISO
VirtualBox
- Enable EFI (for UEFI boot)
- 4GB+ RAM
- Network: NAT or Bridged
- Attach ISO to virtual optical drive
For complete documentation of persistence management, encrypted containers, storage encryption, and safety features, see the health-control documentation.
WiFi Network Setup
WiFi & Network Configuration
Quick WiFi Connect (3 Steps)
Check hardware: ip link show (ensure interface is UP)
Scan networks: sudo nmcli dev wifi list
Connect: sudo nmcli dev wifi connect "SSID" password "PASSWORD"
Connection Methods Overview
Kodachi Terminal supports three WiFi management approaches depending on your preference and system configuration.
Lightweight, fine-grained configuration, no daemon overhead
wpasupplicant package
iw/iwconfig
Open networks, debugging, low-level control
Direct hardware access, minimal dependencies
iw or wireless-tools
Method 1: NetworkManager (Recommended)
NetworkManager provides the most user-friendly WiFi management experience with automatic connection recovery and profile persistence.
Scan and Connect
# List available networkssudonmclidevwifilist
# Connect to WPA2/WPA3 networksudonmclidevwificonnect"NetworkName"password"YourPassword"# Connect to hidden networksudonmclidevwificonnect"HiddenSSID"password"YourPassword"hiddenyes
# Connect to open network (no password)sudonmclidevwificonnect"OpenNetwork"
Connection Management
NetworkManager Commands
Task
Command
Description
Show WiFi status
nmcli radio wifi
Check if WiFi radio is enabled
Enable WiFi
nmcli radio wifi on
Turn on WiFi hardware
Disable WiFi
nmcli radio wifi off
Turn off WiFi hardware
List saved connections
nmcli connection show
Display all saved network profiles
Disconnect from current network
nmcli dev disconnect wlan0
Disconnect WiFi interface (replace wlan0 with your interface)
Reconnect to saved network
nmcli connection up "NetworkName"
Connect to previously saved profile
Delete saved connection
nmcli connection delete "NetworkName"
Remove network profile
Show connection details
nmcli connection show "NetworkName"
Display configuration details
Rescan networks
nmcli dev wifi rescan
Force WiFi scan for available networks
Advanced NetworkManager Configuration
# Set static IP for connectionsudonmcliconnectionmodify"NetworkName"\ipv4.addresses"192.168.1.100/24"\ipv4.gateway"192.168.1.1"\ipv4.dns"1.1.1.1 1.0.0.1"\ipv4.methodmanual
# Revert to DHCPsudonmcliconnectionmodify"NetworkName"ipv4.methodauto
# Set DNS servers (for privacy)sudonmcliconnectionmodify"NetworkName"ipv4.dns"1.1.1.1 1.0.0.1"sudonmcliconnectionmodify"NetworkName"ipv4.ignore-auto-dnsyes
# Disable IPv6 (privacy/anonymity)sudonmcliconnectionmodify"NetworkName"ipv6.methodignore
# Set connection priority (auto-connect preference)sudonmcliconnectionmodify"NetworkName"connection.autoconnect-priority10# Monitor connection events (real-time)nmclimonitor
Method 2: wpa_supplicant (Manual Control)
For users requiring direct WPA2/WPA3 configuration without NetworkManager overhead.
Generate encrypted PSK instead of plaintext passwords: wpa_passphrase "SSID" "password" | sudo tee -a /etc/wpa_supplicant/wpa_supplicant.conf
This stores the encrypted hash instead of your actual password.
Method 3: iw/iwconfig (Low-Level Access)
Direct hardware control for open networks and advanced debugging.
Interface Management
# Show all wireless interfacesiwdev
# Show interface detailsiwdevwlan0info
# Scan for networkssudoiwdevwlan0scan|grep-E"SSID|signal|freq"# Bring interface upsudoiplinksetwlan0up
# Connect to open networksudoiwdevwlan0connect"OpenNetworkSSID"# Disconnectsudoiwdevwlan0disconnect
# Set specific channel (1-13)sudoiwdevwlan0setchannel6
Legacy iwconfig Commands
# View wireless configurationiwconfigwlan0
# Connect to open networksudoiwconfigwlan0essid"OpenNetwork"# Set WEP key (legacy, insecure)sudoiwconfigwlan0keys:YourWEPKey
# Set transmission powersudoiwconfigwlan0txpower20dBm
Troubleshooting WiFi Issues
Hardware and Driver Checks
Diagnostic Commands
Issue
Diagnostic Command
Common Fix
WiFi hardware blocked
rfkill list
sudo rfkill unblock wifi
Interface not found
ip link show
Load driver: sudo modprobe <driver>
Interface is DOWN
ip link show wlan0
sudo ip link set wlan0 up
Kernel driver info
lspci -k | grep -A 3 Network
Check if firmware is loaded
USB WiFi dongle
lsusb | grep -i wireless
Check USB power settings
Driver messages
dmesg | grep -i wifi
Look for firmware errors
Connection failures
sudo iw event
Monitor real-time events while connecting
Signal strength
watch -n 1 'iw dev wlan0 link'
Real-time signal monitoring
Common Troubleshooting Steps
# 1. Unblock WiFi hardwaresudorfkillunblockwifi
# 2. Restart NetworkManagersudosystemctlrestartNetworkManager
# 3. Bring interface up manuallysudoiplinksetwlan0up
# 4. Check for firmware issuesdmesg|grep-ifirmware
# 5. Reload WiFi driver (example for Intel)sudomodprobe-riwlwifi&&sudomodprobeiwlwifi
# 6. Check regulatory domain (affects available channels)iwregget
sudoiwregsetUS# Replace with your country code# 7. Restart wpa_supplicantsudosystemctlrestartwpa_supplicant
# 8. Check interface power management (disable to prevent sleep)sudoiwdevwlan0setpower_saveoff
# 9. Reset network stacksudosystemctlrestartnetworking
# 10. Check for conflicting processespsaux|grep-E"wpa_supplicant|NetworkManager|dhclient"
Persistent Connection Issues?
If WiFi disconnects frequently:
1. Disable power management: sudo iw dev wlan0 set power_save off
2. Make permanent: Add wireless-power off to /etc/network/interfaces
3. Check for channel congestion: Use 5GHz (less crowded) if supported
Supported WiFi Hardware
Kodachi Terminal includes firmware for most common WiFi chipsets. If your hardware isn't working, install the appropriate firmware package.
WiFi Firmware Packages
Chipset/Brand
Package Name
Installation Command
Intel WiFi (most laptops)
firmware-iwlwifi
sudo apt install firmware-iwlwifi
Realtek (USB dongles, laptops)
firmware-realtek
sudo apt install firmware-realtek
Broadcom b43 / b43legacy
Pre-installed at /lib/firmware/b43/ and /lib/firmware/b43legacy/ (extracted into ISO; firmware-b43-installer intentionally excluded because it requires a network fetch that breaks offline builds)
No action (already bundled)
Atheros (older laptops)
firmware-atheros
sudo apt install firmware-atheros
Qualcomm Atheros
firmware-ath9k-htc
sudo apt install firmware-ath9k-htc
Other (MediaTek, Ralink legacy)
Use distribution non-free firmware metapackage if needed (not bundled)
Enable non-free-firmware apt source then sudo apt install firmware-misc-nonfree
Post-Firmware Installation
# After installing firmware, reload the driversudomodprobe-r<driver_name># Unload (e.g., iwlwifi, rtl8xxxu)sudomodprobe<driver_name># Reload# Or reboot the systemsudoreboot
Static IP Configuration
For servers or persistent network setups, configure static IP addressing.
NetworkManager Static IP
# Set static IP via nmclisudonmcliconnectionmodify"NetworkName"\ipv4.addresses"192.168.1.100/24"\ipv4.gateway"192.168.1.1"\ipv4.dns"1.1.1.1,1.0.0.1"\ipv4.methodmanual
# Apply changessudonmcliconnectionup"NetworkName"
Kodachi emphasizes privacy. Use encrypted DNS services to prevent ISP DNS logging.
DNSCrypt Integration
# Enable DNSCrypt (Kodachi service)sudodns-switchdnscrypt-set
# Verify DNSCrypt is runningsudosystemctlstatusdnscrypt-proxy
# Test DNS privacysudodns-leaktest
Manual DNS Configuration
# Set privacy-focused DNS (Cloudflare)sudonmcliconnectionmodify"NetworkName"\ipv4.dns"1.1.1.1 1.0.0.1"\ipv4.ignore-auto-dnsyes
# Or use Quad9 (malware blocking)sudonmcliconnectionmodify"NetworkName"\ipv4.dns"9.9.9.9 149.112.112.112"\ipv4.ignore-auto-dnsyes
# Apply changessudonmcliconnectionup"NetworkName"
Best Practice: DNS Leak Prevention
Always verify DNS privacy after configuration: sudo dns-leak test
This ensures your DNS queries aren't leaking to your ISP or exposing your location.
MAC Address Randomization (Privacy)
Prevent device tracking via MAC address fingerprinting.
# Generate random MAC addresssudoiplinksetwlan0down
sudomacchanger-rwlan0
sudoiplinksetwlan0up
# Or use NetworkManager (persistent per connection)sudonmcliconnectionmodify"NetworkName"\wifi.cloned-mac-addressrandom\wifi.mac-address-randomizationalways
# Apply randomizationsudonmcliconnectionup"NetworkName"# Verify new MACiplinkshowwlan0|grep"link/ether"
# Find least congested channelsudoiwdevwlan0scan|grep-E"freq|signal"|sort
# On your router, switch to channel with least interference# 2.4GHz: Channels 1, 6, 11 (non-overlapping)# 5GHz: More channels available, less congestion
Connection Quality Monitoring
# Real-time signal strengthwatch-n1'iw dev wlan0 link'# Detailed link statisticsiwdevwlan0stationdump
# Network speed test (requires speedtest-cli)speedtest-cli
# Ping test to routerping-c50192.168.1.1|tail-3
Firewall Configuration
# Configure firewall rulessudoiptables-AINPUT-ptcp--dport30050-sTRUSTED_IP-jACCEPT
sudoiptables-AINPUT-ptcp--dport30050-jDROP
# Monitor active connectionssudonetstat-tulpn|grepmicrosocks
Emergency Data Destruction
Emergency Data Destruction (Nuke Password)
What is Nuke Password?
The nuke password feature allows instant, irreversible destruction of encrypted data in emergency scenarios by destroying LUKS encryption keys, making data permanently unrecoverable.
cryptsetup-nuke-password package (pre-installed in the ISO via terminal.list.chroot)
Recommended Method: Using health-control
The health-control binary provides a safe, automated approach to managing nuke passwords with built-in safety features:
# Step 1: Detect LUKS devices on your systemhealth-controlluks-detect
health-controlluks-detect--all-devices# Include loop and virtual deviceshealth-controlluks-detect--json# JSON output for scripts# Step 2: Configure nuke password (Interactive - Recommended)sudohealth-controlluks-nuke--actionconfigure--device/dev/sda5
# Prompts for nuke password interactively (safer method)# OR: Configure with password (Automated - for scripts)sudohealth-controlluks-nuke--actionconfigure--device/dev/sda5--passwordYOUR_NUKE_PASSWORD
# Step 3: Verify nuke password is configuredhealth-controlluks-nuke--actionstatus# Check all LUKS deviceshealth-controlluks-nuke--actionstatus--device/dev/sda5# Check specific devicehealth-controlluks-nuke--actionstatus--json# JSON output# Optional: Remove nuke passwordsudohealth-controlluks-nuke--actionremove--device/dev/sda5
Safety Features
When using health-control for nuke password management, you get:
Automatic LUKS Validation: Verifies device is actually a LUKS partition before operations
Encrypted Header Backup: Creates AES-256-CBC encrypted backup of LUKS header on Desktop (timestamped)
Package Management: Auto-installs cryptsetup-nuke-password if not present
Comprehensive Logging: All operations logged to logs-hook for audit trail
Status Monitoring: Check nuke password status across all LUKS devices
JSON Support: Full JSON output for GUI/dashboard integration
Advanced/Manual Method
For advanced users who prefer direct control, you can use the underlying cryptsetup command:
# Add nuke password to existing LUKS partition (manual method)sudocryptsetupluksAddNuke/dev/sdX2
# You'll be prompted to:# 1. Enter existing LUKS password# 2. Enter new NUKE password (different from normal password)# 3. Confirm nuke password# <i class="fas fa-exclamation-triangle" style="color: #ff9800;"></i> WARNING: Manual method does NOT create header backups# Consider using health-control for automated safety features
How It Works
Normal Boot: Enter regular LUKS password → Data decrypted normally
Emergency Activation: Enter nuke password → LUKS header destroyed instantly → Data permanently unrecoverable
Result: Partition appears as random data, no forensic recovery possible
Activation Process
# During boot, when prompted for LUKS password:# Enter NUKE password instead of normal password# → LUKS header immediately destroyed# → Boot fails (expected)# → Data permanently destroyed
Use Cases
Border crossings / checkpoints under duress
Emergency situations requiring immediate data destruction
Physical device seizure scenarios
Coercive password disclosure situations
Critical Warning
Nuke password destroys ALL data on the encrypted partition permanently. There is NO recovery, NO undo, NO backup restoration. Use only in genuine emergency scenarios. Test in a non-critical environment first.
virt-manager: open the VM settings → Overview → Display Spice/Display VNC → set Keyboard Layout to English (US)
VirtualBox:Settings → General → Advanced → choose English (US) for keyboard layout, or run VBoxManage modifyvm "Kodachi VM" --keyboard-layout "English (US)"
Issue: Binary not found
# Verify binaries exist
ls -la /opt/kodachi/dashboard/hooks/
# Check PATH
echo $PATH
# Run with sudo
sudo ip-fetch
# Check Tor service status
sudo systemctl status tor
# Review Tor logs
sudo journalctl -u tor -f
# Restart Tor service
sudo tor-switch stop-tor
sudo tor-switch torrify-system-nftables-dns
Issue: DNS leaks detected
# Switch DNS provider
sudo dns-switch switch --names dnscrypt-quad9
# Test again
sudo dns-leak test --comprehensive
# Verify DNS configuration
cat /etc/resolv.conf
Security Considerations
Security Considerations
Recommended Security Measures
Always verify downloaded ISOs
Check SHA256 checksums
Use encrypted persistent storage
Enable live-persist-encrypted boot option
Configure nuke password
For emergency data destruction
Restrict proxy access
Use firewall rules to limit client IPs
Regular updates
Keep system packages updated (if using persistence)
Monitor logs
Review service logs for anomalies
Test workflows
Verify anonymity configurations before production use
Backup configurations
Export VPN/proxy configurations separately
Physical security
Secure hardware running proxy server
Network segmentation
Isolate proxy server on dedicated network
Related Documentation
Related Documentation
Installation Guide - General installation instructions for Kodachi binaries
Kodachi ships kodachi-backup, an encrypted backup and restore tool for your personal data, built so you can preserve your files before downloading a new ISO and restore them on the new system afterwards. It wraps restic (encrypted, deduplicated, versioned) and runs entirely from the shell on the Terminal edition.
# Back up to an encrypted volume (LUKS / VeraCrypt / dm-crypt auto-detected)# Add --allow-unencrypted to target an ordinary drive (you will be prompted to confirm)kodachi-backupbackup--target/media/usb
# Restore the latest snapshot into a safe ~/Restored-<date> staging folderkodachi-backuprestore--target/media/usb
# Restore straight to original locations (overwrites current files)kodachi-backuprestore--target/media/usb--in-place
# Integrity check / list snapshots / show statuskodachi-backupverify--target/media/usb
kodachi-backuplist--target/media/usb
kodachi-backupstatus--target/media/usb
# Manage custom folders and view the full backup listkodachi-backupcategories# list all what-to-back-up entries as JSONkodachi-backupadd-path--path<dir># add a custom folder to the backup listkodachi-backupremove-path--path<dir># remove a custom folder from the backup list
What is and isn't backed up
Backs up your data only, Documents, Downloads, Pictures, Videos, Music, Desktop, Public, Templates, plus ~/.gnupg, ~/.ssh, password stores and the LibreWolf profile. It excludes desktop and system configuration (~/.config, ~/.cache, ~/.kde, ~/.local) so a restore can never break a freshly installed ISO. Customize the lists at ~/.config/kodachi/backup/include.list and exclude.list.
Custom folders and crypto wallets
You can back up any folder by running kodachi-backup add-path --path <dir>. Common crypto wallets are automatically included when they exist on disk: Monero (~/.bitmonero and ~/Monero), Bitcoin Core (~/.bitcoin), Electrum (~/.electrum), and Wasabi (~/.walletwasabi). All entries are persisted in ~/.config/kodachi/backup/include.list. Use kodachi-backup categories to see the full list as JSON. Note: wallet data stored under ~/.config is excluded by the desktop-config exclusion rule; the wallets listed above store outside ~/.config and are backed up correctly.
Encryption detection and unencrypted drives
LUKS, VeraCrypt/TrueCrypt, and other dm-crypt volumes are detected automatically. By default, unrecognised (unencrypted) drives are refused. Pass --allow-unencrypted to opt in, you will be warned and must confirm. Restic still encrypts the backup with your passphrase regardless; only the drive's full-disk-encryption layer is absent.
Passphrase
The repository passphrase is never stored, you are prompted on the command line, or you can set the RESTIC_PASSWORD environment variable. You need the same passphrase to restore. Add --json for machine-readable output.
Summary
Summary
Kodachi Terminal Server is the perfect solution for:
Key Benefits
Network-wide proxy protection - Run as dedicated SOCKS5 server
Safe binary testing - Isolated environment for experimentation
Multi-protocol support - 11 routing protocols included
Production ready - Based on Debian 13 (Trixie) with comprehensive hardware support
Complete toolkit - 28 binaries (20 core + 8 KAICS AI) pre-installed in the base ISO
AI-ready - the 8 KAICS ai-* binaries ship pre-installed; AI workflows and models are enabled on demand
Maximum compatibility - 30+ firmware packages for WiFi, Ethernet, Bluetooth
Whether you need a dedicated proxy server for your network or a safe testing environment for Kodachi binaries, Kodachi Terminal Server provides a complete, lightweight solution.