Installation Guide

🛡️ Getting Started with Kodachi Binaries

Beta Release - Community Testing Phase

These binaries are currently in BETA release and undergoing community testing. While the core functionality is stable, this beta phase allows us to refine features and documentation based on real-world usage and feedback.

💡 Testing Recommendation: I advise testing the binaries on a virtual machine first until you become familiar with the commands. Once you're comfortable with how they work, you can safely use them on your main OS.

Have feedback or found a bug? Please share through one of these channels:

Join my Discord community for real-time support and discussions
Submit detailed feedback directly to my inbox via my contact form

Your testing efforts and feedback are invaluable in helping deliver robust, production-ready security tools. Thank you for being part of the Kodachi community!

🛡️ System Requirements

Minimum Requirements

Component	Requirement	Recommended
Operating System	Linux (Debian-based)	Ubuntu 22.04+ / Debian 12+
Architecture	x86_64	x86_64
Memory (RAM)	2GB minimum	4GB or higher
Storage Space	500MB for binaries	1GB for full installation
Linux Kernel	4.15+	5.15+ (LTS)

🛡️ Quick Installation

Two-Step Installation Process

Installation requires two steps

Step 1: Install binaries (no sudo required) Step 2: Install system dependencies (requires sudo)

Step 1: Install Binaries (No Sudo Required)

Default installation to ~/dashboard/hooks

curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-binary-install.sh | bash

Step 2: Install Dependencies (Requires Sudo)

Install recommended packages

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

🛡️ Installation Options

Installation Paths

The installer supports multiple installation locations:

Option	Path	Command
Default	`~/dashboard/hooks`	`curl -sSL ... \\| bash`
Desktop	`~/Desktop/dashboard/hooks`	`curl -sSL ... \\| bash -s -- --desktop`
Custom	User-specified	`curl -sSL ... \\| bash -s -- --path /custom/path`

Additional Installation Parameters

Alternative Installation Paths

# Install to Desktop
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-binary-install.sh | bash -s -- --desktop

# Install to custom path
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-binary-install.sh | bash -s -- --path /opt/kodachi

Version-Specific Installation

# Install specific version
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-binary-install.sh | bash -s -- --version 9.0.2

Dependency Installation Options

# Install minimal packages only
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-deps-install.sh | sudo bash -s -- --minimal

# Install all packages including optional ones
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-deps-install.sh | sudo bash -s -- --full

# Install proxy tools only
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-deps-install.sh | sudo bash -s -- --proxy-only

Manual Binary Installation

# Download binaries archive (contains all files including config and sounds)
wget https://www.kodachi.cloud/apps/os/not_yet_coming_soon/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 base directory structure (some will be populated from archive)
mkdir -p ~/dashboard/hooks/{logs,tmp,backups}

# Copy all binaries to hooks directory
cp binaries/* ~/dashboard/hooks/

# Copy configuration files (includes signkeys, dns-database.json, etc.)
cp -r config ~/dashboard/hooks/

# Copy sound files for notifications
cp -r sounds ~/dashboard/hooks/

# Copy flag icons for country identification
cp -r flags ~/dashboard/hooks/

# Copy binary signatures
mkdir -p ~/dashboard/hooks/results/signatures
cp -r signatures/* ~/dashboard/hooks/results/signatures/

# Create additional runtime directories
mkdir -p ~/dashboard/hooks/others

# Set executable permissions on binaries
chmod +x ~/dashboard/hooks/ip-fetch
chmod +x ~/dashboard/hooks/tor-switch
chmod +x ~/dashboard/hooks/health-control
chmod +x ~/dashboard/hooks/dns-switch
chmod +x ~/dashboard/hooks/routing-switch
chmod +x ~/dashboard/hooks/online-auth
chmod +x ~/dashboard/hooks/integrity-check
chmod +x ~/dashboard/hooks/permission-guard
chmod +x ~/dashboard/hooks/logs-hook
chmod +x ~/dashboard/hooks/deps-checker
chmod +x ~/dashboard/hooks/global-launcher
chmod +x ~/dashboard/hooks/online-info-switch
chmod +x ~/dashboard/hooks/dns-leak
chmod +x ~/dashboard/hooks/oniux
chmod +x ~/dashboard/hooks/tun2socks-linux-amd64

# Download and install system dependencies
wget https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-deps-install.sh
sudo bash kodachi-deps-install.sh

🛡️ System Dependencies

The kodachi-deps-install.sh script installs packages grouped by category:

Package Categories

Category	Packages
Critical (Always)	`curl` `wget` `openssl` `ca-certificates` `coreutils` `findutils` `grep`
Network	`tor` `openvpn` `wireguard-tools` `iptables` `nftables` `iproute2` `iputils-ping` `net-tools` `nyx` `apt-transport-tor` `shadowsocks-libev`
Network (Contrib/Non-free)	`shadowsocks-v2ray-plugin` `v2ray`
DNS	`resolvconf` `dnscrypt-proxy`
Security	`macchanger` `firejail` `apparmor` `apparmor-utils` `apparmor-profiles` `aide` `lynis` `rkhunter` `chkrootkit` `usbguard` `cryptsetup-nuke-password` `fail2ban` `unattended-upgrades` `auditd` `libpam-pwquality` `libpam-google-authenticator`
System	`procps` `psmisc` `systemd` `sudo` `dmidecode` `lsof` `acl` `util-linux` `mount` `uuid-runtime` `inotify-tools` `efibootmgr`
Utilities	`jq` `git` `build-essential` `haproxy` `bleachbit` `secure-delete` `wipe` `nwipe` `rng-tools-debian` `haveged` `ccze` `yamllint` `kitty`
Monitoring	`smartmontools` `lm-sensors` `hdparm` `htop` `iotop` `vnstat`
Audio	`alsa-utils` `pulseaudio` `pulseaudio-utils` `libnotify-bin`
Proxy Tools	`xray` `mieru/mita` `hysteria2`

Automatic Package Handling

Packages marked with * require contrib and non-free repositories

The installation script automatically handles these packages: - If contrib/non-free repositories are enabled: Installs via apt - If repositories are NOT enabled: - shadowsocks-v2ray-plugin - Automatically downloaded from GitHub - v2ray - Skipped (requires manual installation if needed)

The script will inform you during installation if repositories are missing and handle fallback installation automatically.

Installation Modes

Mode	Command	Packages Installed
Recommended	`curl -sSL .../kodachi-deps-install.sh \\| sudo bash`	Critical, Network, DNS, Security, System, Utility, Audio, Monitoring, Proxy Tools
Minimal	`curl -sSL .../kodachi-deps-install.sh \\| sudo bash -s -- --minimal`	Critical, Network only
Full	`curl -sSL .../kodachi-deps-install.sh \\| sudo bash -s -- --full`	All packages including optional ones
Proxy Only	`curl -sSL .../kodachi-deps-install.sh \\| sudo bash -s -- --proxy-only`	xray, mieru, hysteria2 only

🛡️ Configuration

Post-Installation Setup

# The installer creates all necessary directories
# Configuration is stored in ~/dashboard/hooks/config

# For system-wide integration (optional)
~/dashboard/hooks/global-launcher deploy

Directory Structure

After installation, you'll have:

~/dashboard/hooks/
├── ip-fetch                                     # IP geolocation tool
├── tor-switch                                   # Tor management
├── health-control                               # System health monitoring
├── dns-switch                                   # DNS management
├── dns-leak                                     # DNS leak detection
├── routing-switch                               # Multi-protocol routing
├── online-auth                                  # Authentication service
├── integrity-check                              # System integrity verification
├── permission-guard                             # Permission management
├── logs-hook                                    # Centralized logging
├── deps-checker                                 # Dependency validation
├── global-launcher                              # Binary deployment
├── online-info-switch                           # Online information hub
├── config/
│   ├── signkeys/                                # Public signing keys
│   │   ├── public_key.pem                      # Main public key
│   │   └── backup_keys/                        # Backup signing keys
│   ├── dns-database.json                       # DNS server database
│   ├── dns-database-failed.json                # Failed DNS servers
│   ├── os-info.yaml                            # OS version info
│   └── services.conf                           # Service configuration
├── results/
│   └── signatures/                             # Binary signatures
│       ├── ip-fetch.sig
│       ├── tor-switch.sig
│       ├── health-control.sig
│       └── [other binary signatures]
├── sounds/                                     # Notification sounds
│   ├── alert.wav                               # Alert notification
│   ├── warning.wav                             # Warning notification
│   ├── success.wav                             # Success notification
│   └── error.wav                               # Error notification
├── logs/                                       # Application logs (created at runtime)
├── tmp/                                        # Temporary files (created at runtime)
├── backups/                                    # Backup directory (created as needed)
└── others/                                     # Miscellaneous files

🛡️ Verification & Security

Verifying Installation

# Verify all binaries are installed and executable
KODACHI_HOME="$HOME/dashboard/hooks"
echo "Checking binaries..."
for binary in ip-fetch tor-switch health-control dns-switch dns-leak \
              routing-switch online-auth integrity-check permission-guard \
              logs-hook deps-checker global-launcher online-info-switch; do
    if [ -x "$KODACHI_HOME/$binary" ]; then
        version=$($KODACHI_HOME/$binary --version 2>/dev/null | head -1)
        echo "✓ $binary: $version"
    else
        echo "✗ $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 "✓ DNS database present" || echo "✗ DNS database missing"
[ -d "$KODACHI_HOME/config/signkeys" ] && echo "✓ Signing keys directory present" || echo "✗ Signing keys missing"
[ -f "$KODACHI_HOME/config/os-info.yaml" ] && echo "✓ OS info file present" || echo "✗ OS info missing"

# Verify sound files are present
echo -e "\nChecking notification sounds..."
for sound in alert.wav warning.wav success.wav error.wav; do
    [ -f "$KODACHI_HOME/sounds/$sound" ] && echo "✓ $sound present" || echo "✗ $sound missing"
done

# Verify flag icons are present
echo -e "\nChecking flag icons..."
[ -d "$KODACHI_HOME/flags" ] && echo "✓ Flags directory present ($(ls -1 $KODACHI_HOME/flags/*.png 2>/dev/null | wc -l) flags)" || echo "✗ Flags directory missing"

# Verify signatures are present
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 "✓ logs/ is writable" || echo "✗ logs/ is not writable"
[ -w "$KODACHI_HOME/tmp" ] && echo "✓ tmp/ is writable" || echo "✗ tmp/ is not writable"

Signature Verification

The installer automatically verifies binaries against:

Verification Type	Method	Source
Package Signatures	RSA-2048 cryptographic signatures	Embedded in package
Binary Checksums	SHA256 hash verification	Per-binary validation
Remote Validation	Hash comparison with server	Kodachi Cloud servers

Manual Package Verification

To manually verify a downloaded package before installation:

# Download the binary package
wget https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-binaries-v9.0.1.tar.gz

# Download signature and public key
wget https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-binaries-v9.0.1.tar.gz.sig
wget https://www.kodachi.cloud/apps/os/not_yet_coming_soon/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/apps/os/not_yet_coming_soon/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
$KODACHI_HOME/integrity-check check_integrity
# → Shows pass/fail status for each file

Check Binary Signatures

# Verify signatures for all installed binaries
$KODACHI_HOME/integrity-check check_signatures
# → Validates RSA signatures against public key

Check Version Information

# Check version consistency across binaries
$KODACHI_HOME/integrity-check check_version
# → Version comparison results

Run All Verification Checks

# Run comprehensive verification (integrity, signatures, version)
$KODACHI_HOME/integrity-check check_all
# → Complete verification report

Manual Signature Verification

# Or manually verify individual binary signatures
cd ~/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

Path Difference in Docker

Why /opt/kodachi in Docker vs ~/dashboard/hooks for regular installations?

Docker containers: Use /opt/kodachi following the Filesystem Hierarchy Standard (FHS) where /opt is the standard location for add-on application software packages. Containers typically run as root, making /opt accessible.
Regular installations: Default to ~/dashboard/hooks to enable installation WITHOUT sudo/root access. This ensures any user can install the binaries in their home directory.
Both are correct: The installation script's --path parameter provides flexibility to use either location based on your needs.

Using Docker

Essential Package Requirements

The dependency installation script requires procps (for pgrep/pkill) and psmisc (for killall) packages to function properly. 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 to /opt/kodachi (standard for containers)
# Note: Using --path to specify /opt instead of default ~/dashboard/hooks
RUN curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-binary-install.sh | \
    bash -s -- --path /opt/kodachi

# Install system dependencies using the official script (requires sudo)
RUN curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-deps-install.sh | sudo bash

# Add to PATH
ENV PATH="/opt/kodachi:${PATH}"

# Set entrypoint
ENTRYPOINT ["/opt/kodachi/health-control"]

Docker Compose

services:
  kodachi:
    image: kodachi/security-binaries:v9.0.1
    privileged: true
    network_mode: host
    volumes:
      - ./config:/opt/kodachi/config
      - ./logs:/opt/kodachi/logs
    command: ["net-check"]

Building and Running

# Build the Docker image
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)
docker compose up

🛡️ Updates

Manual Updates

To update to the latest version:

# Step 1: Update binaries (no sudo required)
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-binary-install.sh | bash

# Step 2: Update dependencies (requires sudo)
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-deps-install.sh | sudo bash

# Or specify a specific version for binaries
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-binary-install.sh | bash -s -- --version 9.0.2

Version Check

# Check current version of binaries
~/dashboard/hooks/ip-fetch --version
~/dashboard/hooks/integrity-check check_version

Note: Automatic updates are planned for future releases

🛡️ Uninstallation

Complete Removal

# Remove the entire hooks directory
rm -rf ~/dashboard/hooks

# Or if installed elsewhere
rm -rf ~/Desktop/dashboard/hooks
rm -rf /custom/path/dashboard/hooks

Selective Removal

# Keep configuration but remove binaries
cd ~/dashboard/hooks
rm -f ip-fetch tor-switch health-control integrity-check permission-guard
rm -f dns-leak dns-switch routing-switch online-auth logs-hook
rm -f deps-checker global-launcher online-info-switch oniux tun2socks-linux-amd64

🛡️ Troubleshooting

Common Issues

Installation Fails

# Check internet connection
ping -c 3 www.kodachi.cloud

# Try manual download
wget https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-binaries-v9.0.1.tar.gz
# Then extract manually as shown in Manual Installation section

Permission Denied

# Fix permissions
chmod +x ~/dashboard/hooks/*

Binary Not Found

# Run binaries directly with full path
~/dashboard/hooks/tor-switch --version

# Or navigate to the directory
cd ~/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-2048)
# - Individual binary signatures
# - Remote hash validation
# If all three fail for a binary, consider re-downloading

Missing Dependencies

# Run the remote dependency installer
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/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:

# 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, you can run:

# Step 1: Install binaries first
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-binary-install.sh | bash

# Step 2: Install dependencies
curl -sSL https://www.kodachi.cloud/apps/os/not_yet_coming_soon/kodachi-deps-install.sh | sudo bash

# Step 3: Deploy binaries globally (optional)
sudo ~/dashboard/hooks/global-launcher deploy

Tip: After installation, run integrity-check generate to create baseline hashes for system integrity monitoring.