Get Kodachi
Installation Guide
Set up Kodachi binaries safely, verify what you downloaded, and know how to update or remove them. This page covers system requirements, the two-step install, dependency modes, verification, updates, and rollback basics for Debian-based Linux.
Verify first
Two-step install
Debian-based
Update / remove
Getting started with Kodachi binaries
Production release
These binaries are now production-ready and validated across Debian 12/13, Ubuntu 22.04+, and other modern distributions. The workflows, auth model, and security hardening have passed the same QA cycle that ships with Kodachi Terminal Server.
Best practice: new users can still begin inside a virtual machine to learn the commands, then migrate to primary systems once comfortable.
Kodachi Dashboard included
The Kodachi Dashboard is now part of the binary packages. This modern native desktop application provides a unified interface for managing all Kodachi security services. After installation, launch it via the desktop shortcut or run kodachi-dashboard from the terminal.
Need help or want to report an issue?
- Join my Discord community for real-time support and discussions.
- Submit detailed feedback directly to my inbox via my contact form.
Community feedback remains vital, thank you for helping keep Kodachi strong.
Looking for more guides?
User Guides cover every Kodachi binary in depth, and the CLI Reference lists the complete command-line reference.
System requirements
Minimum requirements
| Component | Requirement | Recommended |
|---|---|---|
| Operating System | Linux (Debian-based) | Ubuntu 22.04+ / Debian 12+ / Debian 13 (Trixie) |
| Architecture | x86_64 | x86_64 |
| Memory (RAM) | 4GB minimum | 8GB or higher |
| Storage Space | 20GB free disk | 40GB+ for logs, models, and runtime data |
| Linux Kernel | 4.15+ | 5.15+ (LTS) |
Compatibility and testing
Verified systems: these binaries have been extensively tested on Debian 12 (Bookworm) and Debian 13 (Trixie) and work without issues on x86_64.
Cross-distribution: the Rust binaries are highly portable and will work on most modern Linux distributions (Ubuntu, Fedora, Arch, etc). If you encounter difficulties, they typically stem from system package dependencies, not from the binaries themselves.
Recommended testing environment:
- Download the latest Debian 13 live ISO (curl is already included).
- Install it fresh (physical or virtual machine).
- Run both installation scripts as documented below.
Minimal desktop installs: if you use a minimal desktop ISO (not the live ISO), install curl first:
sudo apt-get update && sudo apt-get install -y curl
The dependency installation script will automatically install required packages like procps (for pgrep/pkill) and psmisc (for killall).
Quick Installation First Release: 03 October 2025 9.8.4 Queen | Binaries last updated 11 July 2026 - build #320
Two-step installation process
Installation requires two steps
Step 1: install binaries (may request sudo for /opt/kodachi/). Step 2: install system dependencies (requires sudo).
Step 1: Install binaries
Package SHA256 Checksum:
f7b3677c59cdb5ecf80954b0614420cd697bf4c669339e8d808f502dad323dd0
The installer verifies both package signature (.sig) and checksum (.sha256) automatically before extraction.
You can also verify the download manually using the browser-based File Verification tool, which computes hashes client-side and compares against all official Kodachi checksums.
Default installation to /opt/kodachi/dashboard/hooks:
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash
Step 2: Install dependencies (requires sudo)
Install recommended packages:
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash
Updating an existing installation?
If you are running this to update an existing installation, stop Permission Guard first to avoid file conflicts. Simplest method: sudo online-auth logout, or stop the daemon with sudo permission-guard --stop-daemon. See the Update & Remove tab for the full flow.
Installation options
Installation paths
The installer supports multiple installation locations:
| Option | Path | Command tail |
|---|---|---|
| Default | /opt/kodachi/dashboard/hooks | ... | bash |
| Desktop | ~/Desktop/dashboard/hooks | ... | bash -s -- --desktop |
| Custom | User-specified | ... | bash -s -- --path /custom/path |
Additional installation parameters
Alternative installation paths
# Install to Desktop
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash -s -- --desktop
# Install to custom path
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash -s -- --path /srv/kodachi
Version-specific installation
# Install specific version
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash -s -- --version 9.0.1
# Install without modifying ~/.bashrc PATH
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash -s -- --skip-path
Dependency installation options
# Full installation (default mode, auto-confirm prompts)
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash
# Explicit full + auto mode (same behavior)
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --full --auto
# Interactive mode (prompts category-by-category)
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh -o kodachi-deps-install.sh && sudo bash kodachi-deps-install.sh --interactive
# Minimal mode (essential + network + privacy/DNS + monitoring + proxy tools)
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --minimal
# Full mode (all major categories; GUI depends on desktop detection)
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --full
# Install proxy tools only (v2ray, xray, hysteria2, mieru)
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --proxy-only
# Disable auto-confirmation prompts
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --no-auto
# Force GUI packages on headless systems
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --force-gui
# Skip GUI packages even if desktop is detected
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --skip-gui
# Install with optional Kicksecure RAM wipe (instead of Kodachi's built-in RAM wipe)
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --full --force-kicksecure-ramwipe
# Verbose output for debugging
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --verbose
Manual binary installation
# Download binaries archive
wget https://www.kodachi.cloud/downloads/installers/binaries/kodachi-binaries-v9.0.1.tar.gz
# Extract archive to temporary directory
tar -xzf kodachi-binaries-v9.0.1.tar.gz
cd kodachi-binaries-v9.0.1
# Create directory structure used by the installer
mkdir -p /opt/kodachi/dashboard/hooks/{config/signkeys,config/profiles,icons,logs,tmp,results/signatures,backups,others,sounds,flags,licenses,binaries-update-scripts,models,data,cache/ip-fetch/ips}
# Copy package contents
cp binaries/* /opt/kodachi/dashboard/hooks/
cp -r config/* /opt/kodachi/dashboard/hooks/config/
cp -r signatures/* /opt/kodachi/dashboard/hooks/results/signatures/
cp -r sounds/* /opt/kodachi/dashboard/hooks/sounds/
cp -r flags/* /opt/kodachi/dashboard/hooks/flags/
cp -r licenses/* /opt/kodachi/dashboard/hooks/licenses/ 2>/dev/null || true
cp -r binaries-update-scripts/* /opt/kodachi/dashboard/hooks/binaries-update-scripts/ 2>/dev/null || true
cp -r models/* /opt/kodachi/dashboard/hooks/models/ 2>/dev/null || true
# Ensure all top-level binaries are executable
find /opt/kodachi/dashboard/hooks -maxdepth 1 -type f -exec chmod 755 {} +
# Install system dependencies
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash
System dependencies
The kodachi-deps-install.sh script installs packages grouped by category.
Package categories (from kodachi-deps-install.sh)
Essential packages
curlwgetopensslca-certificatescoreutilsfindutilsgrepprocpspsmiscsystemdsudodmidecodelsofaclutil-linuxmountuuid-runtimeinotify-toolsntpsecntpsec-ntpdateisc-dhcp-clientpasspwgenxkcdpass
Network & routing
tortorsocksobfs4proxyopenvpnwireguard-toolsiptablesnftablesarptablesebtablesiproute2iputils-pingnet-toolsnyxapt-transport-torshadowsocks-libevredsocksmicrosockshaproxy
Privacy & DNS
dnsutilsbind9-dnsutilssystemd-resolveddnscrypt-proxy v2.1.16qrencode v4.1.1Pi-hole
Security & hardening
ufwmacchangerfirejailapparmorapparmor-utilsapparmor-profilesaidelynisrkhunterchkrootkitusbguardecryptfs-utilscryptsetupcryptsetup-initramfscryptsetup-nuke-passwordfail2banunattended-upgradesauditdlibpam-pwqualitylibpam-google-authenticatorsecure-deletewipenwipe
Advanced tools
jqgitbuild-essentialrng-tools-debianhavegedcczeyamllintsmartmontoolslm-sensorshdparmhtopiotopvnstatefibootmgrrfkillethtoollsb-releasepciutils
System monitoring
btopiftopnethogsncdunloadiperf3speedtest-cli
GUI applications
bleachbitkittyfontconfigfonts-noto-color-emojiconky-allalsa-utilspulseaudiopulseaudio-utilslibnotify-binxclipxselmpvxtermnetwork-manager
Proxy tools (Contrib)
v2rayxraymieru v3.33.0hysteria2 v2.9.2shadowsocks-v2ray-plugin
"Contrib" category
In the Installation Modes table below, "Contrib" refers to the apt contrib / non-free repository packages, the same proxy tools listed under the Proxy Tools card above (v2ray, xray, shadowsocks-v2ray-plugin). There is no separate "Contrib" card; the two names describe the same set.
Special handling performed by the installer:
The installation script automatically handles these packages:
- Pi-hole Installed via official installer script (auto in non-interactive mode; prompted in interactive mode)
- shadowsocks-v2ray-plugin Downloaded from GitHub (v1.3.2) if contrib/non-free not available
- v2ray Requires contrib/non-free repos or manual installation from GitHub
- dnscrypt-proxy Downloaded from GitHub (v2.1.16) with apt fallback
- qrencode Compiled from GitHub source (v4.1.1) with apt fallback
- resolvconf/openresolv The installer handles compatibility between resolvconf and openresolv. If resolvconf
conflicts with systemd-resolved, openresolv is installed as an alternative so VPN tools
still get the resolvconf command
- systemd-resolved Modern DNS resolver with caching (Debian 12+ separate package). Configured to work
alongside dnscrypt-proxy/Pi-hole by disabling the stub listener when other DNS services
are active to avoid port 53 conflicts
- kloak Keystroke anonymization tool compiled from source (v0.2)
- grub-common/grub2-common GRUB bootloader tools auto-detected for health-control RAM wipe support. Enables the
init_on_free=1 kernel parameter. On live systems or non-GRUB bootloaders these are skipped
RAM wipe functionality
Kodachi has built-in RAM wipe via the health-control memory-wipe command, installed by default with the binaries. If you prefer Kicksecure's ram-wipe package instead, use --force-kicksecure-ramwipe:
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --full --force-kicksecure-ramwipe
The script will inform you during installation if repositories are missing and handle fallback installation automatically.
Installation modes
| Mode | Command | Packages installed |
|---|---|---|
| Full (default) | curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash |
Essential, Network, Privacy, Security, Advanced, Monitoring, Contrib, Proxy Tools (+ GUI if desktop is detected) |
| Minimal | curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --minimal |
Essential, Network, Privacy, Monitoring, Contrib, Proxy Tools (+ Pi-hole and DNS tooling) |
| Interactive | curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh -o kodachi-deps-install.sh && sudo bash kodachi-deps-install.sh --interactive |
Prompts for each category; same package sources as full mode but user-selected |
| Proxy Only | curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash -s -- --proxy-only |
v2ray, xray, mieru v3.33.0, hysteria2 v2.9.2 |
Configuration
Post-installation setup
# The installer creates all necessary directories
# Configuration is stored in /opt/kodachi/dashboard/hooks/config
# For system-wide integration (optional)
cd /opt/kodachi/dashboard/hooks && sudo ./global-launcher deploy
Directory structure
Installation directory layout
/opt/kodachi/dashboard/hooks/ ├── ai-admin # AI admin tool ├── ai-cmd # AI command engine ├── ai-discovery # AI discovery tool ├── ai-gateway # AI agent command gateway ├── ai-learner # AI learner ├── ai-monitor # AI monitoring tool ├── ai-scheduler # AI scheduler ├── ai-trainer # AI trainer ├── conky-status # Conky details telemetry gateway ├── deps-checker # Dependency validation ├── dns-leak # DNS leak testing ├── dns-switch # DNS manager ├── global-launcher # Global deploy helper ├── health-control # Security/health controls ├── integrity-check # Signature/integrity checker ├── ip-fetch # IP and network intelligence ├── kodachi-dashboard # Desktop dashboard ├── kodachi-session-helper # Desktop session helper ├── kodachi-soc # Security operations center / threat detection ├── logs-hook # Log aggregator ├── online-auth # Session/auth actions ├── online-info-switch # Online intelligence mode switch ├── oniux # CLI helper tool (companion) ├── permission-guard # Runtime permission daemon/control ├── routing-switch # Routing and path switcher ├── tor-switch # Tor mode manager ├── tun2socks-linux-amd64 # tun2socks binary (companion) ├── workflow-manager # Workflow orchestration ├── config/ │ ├── signkeys/ # Public signing keys │ │ └── public_key_v*.pem # Versioned public keys │ ├── profiles/ # Workflow profile templates │ ├── icons/ # Legacy icon fallback location │ ├── dns-database.json # DNS server database (336 servers) │ ├── dns-database-failed.json # Failed DNS servers │ ├── build-meta.json # Build/version metadata (per-edition) │ └── services.conf # Service configuration ├── icons/ # Runtime icon location │ └── kodachi-dashboard.png ├── results/ │ └── signatures/ # Binary signatures + metadata │ ├── <binary>_v*.sig │ └── <binary>_v*.sig.info ├── binaries-update-scripts/ # Embedded update scripts ├── sounds/ # Notification sounds ├── flags/ # Country flags ├── licenses/ # License files ├── models/ # Essential AI models (ONNX + embeddings; GGUF via ai-trainer) ├── kodachi-ai/ │ └── models -> ../models # Compatibility link ├── rust/ │ └── kodachi-ai/ │ └── models -> ../../models # Compatibility link ├── cache/ │ └── ip-fetch/ │ └── ips/ # ip-fetch cache ├── data/ # Runtime data files ├── logs/ # Logs (runtime) ├── tmp/ # Temporary files (runtime) ├── backups/ # Backups └── others/ # Miscellaneous runtime files
Verification & security
Verifying installation
# Verify all packaged binaries are installed and executable
KODACHI_HOME="/opt/kodachi/dashboard/hooks"
echo "Checking binaries..."
BINARIES=(
deps-checker dns-leak dns-switch global-launcher health-control integrity-check ip-fetch
kodachi-dashboard kodachi-soc kodachi-session-helper conky-status logs-hook online-auth
online-info-switch oniux permission-guard routing-switch tor-switch tun2socks-linux-amd64
workflow-manager
ai-cmd ai-trainer ai-learner ai-admin ai-monitor ai-scheduler ai-discovery ai-gateway
)
for binary in "${BINARIES[@]}"; do
if [ -x "$KODACHI_HOME/$binary" ]; then
version=$("$KODACHI_HOME/$binary" --version 2>/dev/null | head -1 || true)
[ -n "$version" ] && echo "[OK] $binary: $version" || echo "[OK] $binary: installed"
else
echo "[MISSING] $binary: not installed or not executable"
fi
done
# Verify configuration files are present
echo -e "\nChecking configuration files..."
[ -f "$KODACHI_HOME/config/dns-database.json" ] && echo "[OK] DNS database present" || echo "[MISSING] DNS database missing"
[ -d "$KODACHI_HOME/config/signkeys" ] && echo "[OK] Signing keys directory present" || echo "[MISSING] Signing keys missing"
[ -f "$KODACHI_HOME/config/build-meta.json" ] && echo "[OK] Build metadata present" || echo "[MISSING] build-meta.json missing"
# Verify notification sounds
echo -e "\nChecking notification sounds..."
for sound in alert.wav warning.wav success.wav error.wav; do
[ -f "$KODACHI_HOME/sounds/$sound" ] && echo "[OK] $sound present" || echo "[MISSING] $sound missing"
done
# Verify flag icons
echo -e "\nChecking flag icons..."
[ -d "$KODACHI_HOME/flags" ] && echo "[OK] Flags directory present ($(ls -1 $KODACHI_HOME/flags/*.png 2>/dev/null | wc -l) flags)" || echo "[MISSING] Flags directory missing"
# Verify signatures
echo -e "\nChecking binary signatures..."
sig_count=$(ls -1 $KODACHI_HOME/results/signatures/*.sig 2>/dev/null | wc -l)
echo "Found $sig_count binary signatures"
# Check directory permissions
echo -e "\nChecking directory permissions..."
[ -w "$KODACHI_HOME/logs" ] && echo "[OK] logs/ is writable" || echo "[WARN] logs/ is not writable"
[ -w "$KODACHI_HOME/tmp" ] && echo "[OK] tmp/ is writable" || echo "[WARN] tmp/ is not writable"
Signature verification
The installer automatically verifies binaries against:
| Verification type | Method | Source |
|---|---|---|
| Package signature | RSA signature check with OpenSSL | kodachi-binaries-*.tar.gz.sig |
| Package checksum | SHA256 checksum verification | kodachi-binaries-*.tar.gz.sha256 |
| Per-binary signature check | Signature check for each extracted file | signatures/<binary>_v*.sig |
Manual package verification
To manually verify a downloaded package before installation:
# Download the binary package
wget https://www.kodachi.cloud/downloads/installers/binaries/kodachi-binaries-v9.0.1.tar.gz
# Download signature and public key
wget https://www.kodachi.cloud/downloads/installers/binaries/kodachi-binaries-v9.0.1.tar.gz.sig
wget https://www.kodachi.cloud/downloads/installers/binaries/public_key_v9.0.1.pem
# Verify package signature
openssl dgst -sha256 -verify public_key_v9.0.1.pem \
-signature kodachi-binaries-v9.0.1.tar.gz.sig \
kodachi-binaries-v9.0.1.tar.gz
# Verify package checksum
wget https://www.kodachi.cloud/downloads/installers/binaries/kodachi-binaries-v9.0.1.tar.gz.sha256
sha256sum -c kodachi-binaries-v9.0.1.tar.gz.sha256
Verifying installed binaries
Check file integrity (hashes)
# Verify file hashes for all installed binaries
integrity-check check-integrity
# Shows pass/fail status for each file
Check binary signatures
# Verify signatures for all installed binaries
integrity-check check-signatures
# Validates RSA signatures against public key
Check version information
# Check version consistency across binaries
integrity-check check-version
# Version comparison results
Run all verification checks
# Run comprehensive verification (integrity, signatures, version)
integrity-check check-all
# Complete verification report
Manual signature verification
# Or manually verify individual binary signatures
cd /opt/kodachi/dashboard/hooks
for sig in results/signatures/*.sig; do
binary=$(basename "$sig" .sig | cut -d'_' -f1)
if [ -f "$binary" ]; then
openssl dgst -sha256 -verify config/signkeys/public_key_v9.0.1.pem \
-signature "$sig" "$binary"
fi
done
Docker installation
Default installation path
Both Docker and regular installations default to /opt/kodachi/dashboard/hooks. This follows the Filesystem Hierarchy Standard (FHS), where /opt is the standard location for add-on application software. The binary installer requests sudo once to create /opt/kodachi/ and set ownership to the current user; no root access is needed after that. The --path parameter can override to a custom location.
Using Docker
Essential package requirements
The dependency installation script requires procps (for pgrep/pkill) and psmisc (for killall). These must be installed before running the dependency script.
FROM debian:trixie-slim
# Set environment to avoid interactive prompts
ENV DEBIAN_FRONTEND=noninteractive
# Remove default sources and add contrib/non-free repositories
RUN rm -f /etc/apt/sources.list.d/debian.sources && \
echo "deb http://deb.debian.org/debian/ trixie main contrib non-free non-free-firmware" > /etc/apt/sources.list && \
echo "deb http://security.debian.org/debian-security trixie-security main contrib non-free non-free-firmware" >> /etc/apt/sources.list && \
echo "deb http://deb.debian.org/debian/ trixie-updates main contrib non-free non-free-firmware" >> /etc/apt/sources.list
# Install apt-utils first to avoid debconf warnings
RUN apt-get update && apt-get install -y --no-install-recommends \
apt-utils \
&& rm -rf /var/lib/apt/lists/*
# Configure debconf to prevent resolvconf installation issues in Docker
RUN apt-get update && apt-get install -y debconf-utils && \
echo 'debconf debconf/frontend select Noninteractive' | debconf-set-selections && \
echo "resolvconf resolvconf/linkify-resolvconf boolean false" | debconf-set-selections && \
rm -rf /var/lib/apt/lists/*
# Install essential dependencies that the scripts need
RUN apt-get update && apt-get install -y \
curl wget openssl ca-certificates sudo \
procps psmisc \
coreutils findutils grep \
&& rm -rf /var/lib/apt/lists/*
# Install Kodachi binaries (defaults to /opt/kodachi/dashboard/hooks)
RUN curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash
# Install system dependencies using the official script (requires sudo)
RUN curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash
# Add to PATH
ENV PATH="/opt/kodachi/dashboard/hooks:${PATH}"
# Set entrypoint
ENTRYPOINT ["health-control"]
Docker Compose
Build the image yourself
There is no published Kodachi container image on any registry. Build the image locally from the Dockerfile above first (see "Building and running"), then this compose file uses that locally built image via build: ..
services:
kodachi:
build: .
image: kodachi-binaries:v9.0.1
privileged: true
network_mode: host
volumes:
- ./config:/opt/kodachi/dashboard/hooks/config
- ./logs:/opt/kodachi/dashboard/hooks/logs
command: ["net-check"]
Building and running
# Build the Docker image from the Dockerfile above
docker build -t kodachi-binaries:v9.0.1 .
# Run a container
docker run --rm --privileged kodachi-binaries:v9.0.1 net-check
# Or with docker compose (v2), which builds the image first
docker compose up --build
Updates
Manual updates
To update to the latest version:
# Step 1: Update binaries (no sudo required)
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash
# Step 2: Update dependencies (requires sudo)
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash
# Or specify a specific version for binaries
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash -s -- --version 9.0.1
Updating existing installation
Stop Permission Guard before updating
The permission-guard service must be stopped to avoid file permission conflicts during updates. Simplest method: log out, run the update scripts, then log back in. Or stop the daemon manually with one of the commands below.
# Stop the daemon manually
sudo permission-guard --stop-daemon
# OR
sudo online-auth disable-permission-guard
# Verify permission-guard is disabled
sudo permission-guard --daemon-status
# OR
sudo online-auth permission-guard-status
Once permission-guard is stopped, run both update scripts:
# Step 1: Update binaries (no sudo required)
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash
# Step 2: Update dependencies (requires sudo)
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash
# Step 3: Verify the update
integrity-check check-version
Alternative installation paths
If you installed to a custom location (for example --desktop or --path), use the correct path:
# Default/canonical installation path
sudo /opt/kodachi/dashboard/hooks/permission-guard --daemon-status
# For custom --path installation
sudo /custom/path/permission-guard --daemon-status
Version check
# Check current version of binaries
ip-fetch --version
integrity-check check-version
Note: automatic updates are planned for future releases.
Uninstallation
Stop services first
As with updates, log out or stop permission-guard (sudo online-auth logout or sudo permission-guard --stop-daemon) before removing files, so the daemon is not holding anything open.
Complete removal
# Remove the entire hooks directory
rm -rf /opt/kodachi/dashboard/hooks
# Or if installed elsewhere
rm -rf ~/Desktop/dashboard/hooks
rm -rf /custom/path
Selective removal
# Keep configuration but remove binaries
cd /opt/kodachi/dashboard/hooks
rm -f deps-checker dns-leak dns-switch global-launcher health-control integrity-check ip-fetch
rm -f kodachi-dashboard kodachi-soc kodachi-session-helper conky-status logs-hook online-auth online-info-switch oniux permission-guard
rm -f routing-switch tor-switch tun2socks-linux-amd64 workflow-manager
rm -f ai-cmd ai-trainer ai-learner ai-admin ai-monitor ai-scheduler ai-discovery
rm -f ai-gateway
Troubleshooting
Common issues
Installation fails
Solution
# Check internet connection
ping -c 3 www.kodachi.cloud
# Try manual download
wget https://www.kodachi.cloud/downloads/installers/binaries/kodachi-binaries-v9.0.1.tar.gz
# Then extract manually as shown in the Install tab
Permission denied
Solution
# Fix permissions
chmod +x /opt/kodachi/dashboard/hooks/*
Binary not found
Solution
# Run binaries directly with full path
tor-switch --version
# Or navigate to the directory
cd /opt/kodachi/dashboard/hooks
tor-switch --version
Signature verification warnings
Signature verification warnings are informational; the installer continues with installation. Multiple verification layers ensure security:
- Package signature (RSA-4096)
- Individual binary signatures
- Package SHA256 checksum validation
If all three fail for a binary, consider re-downloading.
Missing dependencies
Solution
# Run the remote dependency installer
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash
# Or install required packages manually
sudo apt install tor iptables openssl curl wget
Not in sudoers group
If you see "User is NOT in the sudoers group" when running scripts:
Solution
# Switch to root user
su -
# Add your user to sudo group (replace USERNAME with your actual username)
usermod -aG sudo USERNAME
# Exit root session
exit
# Log out and log back in for changes to take effect
After adding yourself to sudoers
# Step 1: Install binaries first
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash
# Step 2: Install dependencies
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-deps-install.sh | sudo bash
# Step 3: Deploy binaries globally (optional)
cd /opt/kodachi/dashboard/hooks && sudo ./global-launcher deploy
Tip
After installation, run integrity-check generate to create baseline hashes for system integrity monitoring.
Getting started quick reference
A condensed recap of the commands above. The full detail lives in the Install, Verify, and Update tabs.
One-line installer (recommended)
# Default installation to /opt/kodachi/dashboard/hooks
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash
# Install to Desktop
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash -s -- --desktop
# Custom installation path
curl -sSL https://www.kodachi.cloud/apps/os/install/kodachi-binary-install.sh | bash -s -- --path /custom/path
Post-installation setup
# The installer adds a "KODACHI PATH" block to ~/.bashrc automatically
# (sets KODACHI_HOME and prepends it to PATH), unless you used --skip-path.
# To use the binaries in your current shell without opening a new terminal:
source ~/.bashrc
# If you installed with --skip-path, add the directory to PATH manually:
export PATH="/opt/kodachi/dashboard/hooks:$PATH"
# Verify installation
ip-fetch --version
tor-switch --version
health-control --version
Quick troubleshooting
Connection issues
# Recover routing/network issues
sudo routing-switch recover
# Recover internet connectivity
sudo health-control recover-internet --force
# Reset DNS to defaults
sudo dns-switch restore-default
Authentication problems
# Re-authenticate
sudo online-auth logout
sudo online-auth authenticate
# For long sessions, use --relogin for automatic reconnection
sudo online-auth authenticate --relogin
# Check if blocked
online-auth check-if-blocked
Next steps
After installation
- Open Binary Suite Overview for the suite map.
- Open Generated CLI Reference for exact commands and flags.
- Open the category hubs for safe workflows: Network, Security, Protection, and Infrastructure.
Keep this page focused
- Installation, update, removal, dependency modes, and verification stay here.
- Desktop ISO and Terminal ISO behavior stay on their edition pages.
- Support, licensing, and payment details stay on the Support page.
Quick reference
# Help and examples for any binary
<binary-name> -h
<binary-name> -e
# JSON output for automation
<binary-name> --json
# Human-readable JSON output
<binary-name> --json --pretty