Infrastructure guide
Deps Checker Guide
Validate that every Kodachi Rust binary has the system packages it needs, and generate install scripts when they do not. This guide covers pre-install checks, profile-based installs, and CI gating.
Dependencies
Validation
SBOM
CI
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
File Information
| Property | Value |
|---|---|
| Binary Name | deps-checker |
| Version | 9.8.4 (build 319) |
| Build Date | Not disclosed |
| Rust Version | rustc 1.96.0 (ac68faa20 2026-05-25) |
| File Size | 2.8MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Infrastructure & Management |
| Description | Dependency checker for Kodachi OS Rust binaries - Validates system dependencies and generates instal... |
| JSON Data | View Raw JSON |
SHA256 Checksum
Key Features
Dependency Management
| Feature | Description |
|---|---|
| Comprehensive Scanning | Identifies all dependencies for Rust services |
| Validation Engine | Verifies each dependency is installed and working |
| Auto-Installation | Generates scripts to install missing dependencies |
| Version Checking | Ensures dependencies meet minimum version requirements |
Why Deps Checker is Critical
| Benefit | Description |
|---|---|
| Service Reliability | Prevents services from failing due to missing dependencies |
| System Validation | Ensures system is properly configured |
| Quick Recovery | Rapidly identifies and fixes dependency issues |
| Installation Helper | Simplifies setup on new systems |
TL;DR - Essential Commands
# Check dependencies for a specific binary
deps-checker check dns-switch
# Check all binaries
deps-checker check-all
# Install missing packages for all binaries
sudo deps-checker install-missing all
# List all known binaries
deps-checker list-binaries
Understanding Dependency Management
How Deps Checker Works
Deps Checker analyzes each Rust binary to determine its requirements:
# Check dependencies for all services
deps-checker check-all
# What it checks:
# - System libraries (OpenSSL, libcurl, etc.)
# - Runtime dependencies (Python, Node.js if needed)
# - Configuration files
# - Network tools (iptables, nftables, etc.)
Checking Services
Analyze specific services for dependencies:
# Check single service
deps-checker check ip-fetch
# Check with specific profile (minimal or full)
deps-checker check ip-fetch --profile minimal
# Check all services
deps-checker check-all
# Check all with JSON output
deps-checker check-all --json
Verification Process
# Check all dependencies and their status
deps-checker check-all
# Output shows:
# <i class="fas fa-check" style="color: #4CAF50;"></i> OpenSSL 3.0.2 - INSTALLED
# <i class="fas fa-check" style="color: #4CAF50;"></i> libcurl 7.81.0 - INSTALLED
# <i class="fas fa-times" style="color: #f44336;"></i> nftables - MISSING
# <i class="fas fa-exclamation-triangle" style="color: #ff9800;"></i> iptables 1.8.4 - VERSION TOO OLD (need 1.8.7+)
# Save report to file
deps-checker check-all --json -o deps-check-report.json
# Quick pass/fail for CI
deps-checker check-all --json | jq -e '.summary.with_missing == 0' >/dev/null
Generating Installation Scripts
When dependencies are missing:
# Generate installation script from check results
deps-checker check-all --json | deps-checker generate-script
# Generate for different shells
deps-checker check-all --json | deps-checker generate-script --shell zsh
# Generate and execute immediately (review before executing)
deps-checker check-all --json | sudo deps-checker generate-script --execute
# Preview without executing
deps-checker check-all --json | deps-checker generate-script --dry-run
Dependency Reports
Generate comprehensive dependency documentation:
# Generate full dependency check report
deps-checker check-all --json -o deps-check-report.json
# Generate Software Bill of Materials (SBOM)
deps-checker check-all --sbom -o deps-check-sbom.json
# Review report summary with jq
cat deps-check-report.json | jq '.summary'
# Check if all dependencies satisfied (exit code check)
deps-checker check-all --json | jq '.summary.exit_code'
Service-Specific Dependencies
Each service has unique requirements:
# Check routing-switch dependencies
deps-checker check routing-switch
# Requires: openvpn, wireguard-tools, tun2socks
# Check health-control dependencies with minimal profile
deps-checker check health-control -p minimal
# Core dependencies only
# Check health-control with full profile
deps-checker check health-control -p full
# Includes audio, security tools, etc.
# List available profiles for a binary
deps-checker list-profiles health-control
Fixing Missing Dependencies
# Install missing packages for specific binary
sudo deps-checker install-missing dns-leak
# Install all missing packages system-wide
sudo deps-checker install-missing all
# What it does:
# 1. Identifies missing packages
# 2. Installs via apt-get
# 3. Verifies installation
# 4. Reports status
Dependency Profiles and Binaries
# List all supported binaries
deps-checker list-binaries
# List available profiles (minimal/full) for a binary
deps-checker list-profiles health-control
# Use custom dependency database
deps-checker check-all --db ./custom-deps-db
# Strict mode - treat warnings as errors
deps-checker check-all --strict
Common Workflows
# Typical workflow - check then install
deps-checker check-all # See what's missing
sudo deps-checker install-missing all # Install everything
# CI/CD integration - fail on warnings
deps-checker check-all --strict || exit 1
# Automated validation
deps-checker check-all --json | jq '.summary.exit_code'
# Generate and review before installing
deps-checker check-all --json | deps-checker generate-script --dry-run
Advanced Commands
For advanced users who need access to all available commands and options, please refer to the auto-generated command reference which includes:
| Feature | Description |
|---|---|
| Custom Paths | Custom dependency paths |
| Version Constraints | Version constraint specifications |
| Platform Checks | Platform-specific checks |
| Dev Dependencies | Development dependencies |
| Container Validation | Docker/container validation |
| JSON Formatting | JSON output formatting |
| CLI Reference | All command-line flags and parameters |
Security Notes
Important Security Practices:
| Practice | Description |
|---|---|
| Source Verification | Verify package sources before installation |
| Script Review | Review installation scripts before execution |
| Database Updates | Keep dependency database updated |
| Security Updates | Check for security updates regularly |
| Official Repos | Use official repositories only |
Performance
| Metric | Value |
|---|---|
| Scan Speed | < 5 seconds for all services |
| Memory Usage | ~25MB during scanning |
| CPU Usage | < 10% during checks |
| Database Size | ~2MB |
| Verification Time | < 1 second per dependency |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: Pre-Installation System Dependency Validation
Quick validation before installing Kodachi OS to ensure the system meets all requirements.
# Step 1: Check all dependencies with strict mode
deps-checker check-all --strict
# Expected: Exit code 1 if any warnings or missing dependencies
# Step 2: Generate comprehensive report for review
deps-checker check-all --json -o pre-install-deps-report.json
# Expected: JSON report saved to file
# Step 3: Review summary to identify critical issues
cat pre-install-deps-report.json | jq '.summary'
# Expected: Count of satisfied/missing/conflicting dependencies
# Step 4: Verify system integrity before proceeding
integrity-check check-all --timeout 300
# Expected: Signature and hash validation passed
# Step 5: Generate installation script for missing packages
deps-checker check-all --json | deps-checker generate-script --dry-run
# Expected: Preview of installation commands without execution
Cross-binary workflow: deps-checker + global-launcher + integrity-check
When to run: Before initial Kodachi OS installation or major system upgrades. Automate this with workflow-manager for deployment pipelines.
Scenario 2: Automated Dependency Installation (All or Specific)
Install missing dependencies either system-wide or for specific services.
# Step 1: Check what's missing across all binaries
deps-checker check-all
# Expected: Overview of missing dependencies per binary
# Step 2: Install for specific critical service first
sudo deps-checker install-missing health-control
# Expected: Package installation for health-control only
# Step 3: Verify health-control dependencies satisfied
deps-checker check health-control --json | jq -e '.summary.with_missing == 0'
# Expected: Boolean true if all dependencies installed
# Step 4: Install all remaining missing packages
sudo deps-checker install-missing all
# Expected: System-wide installation of all missing packages
# Step 5: Verify complete system dependency satisfaction
deps-checker check-all --strict --json -o post-install-verification.json
# Expected: Exit code 0, all dependencies satisfied
# Step 6: Launch services via global-launcher
cd /opt/kodachi/dashboard/hooks && sudo ./global-launcher deploy
# Expected: Service starts without dependency errors
Cross-binary workflow: deps-checker + global-launcher
When to run: After fresh Kodachi OS installation or when adding new services.
Scenario 3: Profile-Based Installation (Minimal vs Full)
Use dependency profiles for optimized installations based on use case.
# Step 1: Check available profiles for health-control
deps-checker list-profiles health-control
# Expected: List showing 'minimal' and 'full' profiles
# Step 2: Install minimal profile for lightweight deployment
deps-checker check health-control -p minimal --json -o health-minimal-deps.json
# Expected: Core dependencies only
# Step 3: Install minimal dependencies
sudo deps-checker install-missing health-control -p minimal
# Expected: Installation of essential packages only
# Step 4: Verify minimal health-control functionality
health-control net-check
# Expected: Basic network check works with minimal dependencies
# Step 5: Upgrade to full profile for advanced features
deps-checker check health-control -p full --json -o health-full-deps.json
# Expected: Complete dependency list including optional features
# Step 6: Install additional packages for full profile
sudo deps-checker install-missing health-control -p full
# Expected: Audio, security tools, and advanced features installed
# Step 7: Verify Tor functionality with full dependencies
tor-switch tor-status
# Expected: Full Tor service operational with all features
Cross-binary workflow: deps-checker + health-control + tor-switch
When to run: For resource-constrained systems (minimal) or full-featured installations (full).
Scenario 4: Script Generation for Deployment Pipelines
Generate reusable installation scripts for automated deployments.
# Step 1: Check dependencies for all services
deps-checker check-all --json -o deployment-deps-report.json
# Expected: Complete dependency analysis saved
# Step 2: Generate bash script for deployment automation
deps-checker check-all --json | deps-checker generate-script --shell bash -o install-deps.sh
# Expected: Executable bash script created
# Step 3: Generate zsh script for alternative shell environments
deps-checker check-all --json | deps-checker generate-script --shell zsh -o install-deps.zsh
# Expected: Zsh-compatible script created
# Step 4: Preview script before deployment
deps-checker check-all --json | deps-checker generate-script --dry-run
# Expected: Script output displayed without execution
# Step 5: Execute installation script in deployment pipeline
sudo bash install-deps.sh
# Expected: All dependencies installed automatically
# Step 6: Integrate with workflow-manager for orchestration
workflow-manager run --step "deps-checker check-all --strict"
# Expected: Dependency validation as workflow step
Cross-binary workflow: deps-checker + workflow-manager
When to run: When creating CI/CD pipelines or automated deployment workflows. Automate this with workflow-manager for repeatable deployments.
Scenario 5: CI/CD Integration with SBOM Generation
Integrate dependency checking into CI/CD pipelines with Software Bill of Materials generation.
# Step 1: Run strict dependency check (fail on warnings)
deps-checker check-all --strict || exit 1
# Expected: Exit code 1 if any warnings exist (fails CI build)
# Step 2: Generate CycloneDX SBOM for security scanning
deps-checker check-all --sbom -o deps-sbom.json
# Expected: SBOM in CycloneDX format for vulnerability analysis
# Step 3: Verify all dependencies satisfied for CI gate
deps-checker check-all --json | jq -e '.summary.with_missing == 0' >/dev/null
# Expected: Exit code 0 if all dependencies satisfied
# Step 4: Check exit code for automated decision making
deps-checker check-all --json | jq '.summary.exit_code'
# Expected: Numeric exit code (0 = success, 1 = issues)
# Step 5: Verify binary signatures and integrity
integrity-check check-all --timeout 300
# Expected: All binaries pass signature verification
# Step 6: Save comprehensive reports for compliance audit
deps-checker check-all --json -o ci-deps-report.json
# Expected: Complete dependency report with timestamps
# Step 7: Use custom dependency database for CI environment
deps-checker check-all --db ./ci-deps-db --strict
# Expected: Validation against CI-specific dependency definitions
Cross-binary workflow: deps-checker + integrity-check
When to run: In every CI/CD pipeline run before building or deploying. Ensures reproducible builds and tracks dependency changes.
Related Workflows
- health-control, System health monitoring requiring specific dependencies
- tor-switch, Tor network management with profile-based dependencies
- integrity-check, Binary verification and signature validation
- global-launcher, Service orchestration after dependency installation
- workflow-manager, Automated workflow integration for deployments
- Full CLI Reference: deps-checker commands