Infrastructure guide
Deps Checker Guide
Validate that Kodachi's binaries have the system packages they need, 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 | 10.0.3 (build 75) |
| Build Date | Not disclosed |
| Rust Version | rustc 1.98.0 (88d9e12ae 2026-08-18) |
| File Size | 3.0MB |
| 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
dc7a34e7c9de312509917abc07bab554cf50dce24a9f6630f86388b6fecceef6
Key Features
Dependency Management
| Feature | Description |
|---|---|
| Comprehensive Scanning | Lists each binary's required and optional packages from its built-in dependency database |
| Validation Engine | Verifies each package is installed and that the commands it provides are present |
| 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 reads a built-in dependency database (one manifest per binary, 30 binaries) and checks the system against it:
# Check dependencies for all services
deps-checker check-all
# What it checks:
# - Operating system packages and the commands they provide (curl, iproute2, openssl, systemd, ...)
# - VPN, proxy and Tor clients (openvpn, wireguard-tools, tor, ...), most of them optional
# - Minimum package versions, plus the services a binary manages or conflicts with
# - Firewall and network tools (iptables, nftables, ...)
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, per binary:
# routing-switch (profile: full, status: missing) depends on N operating system packages:
# Dependencies overview (N total, N satisfied, 1 missing):
# ✓ Installed: iproute2, openvpn, procps, ...
# ✗ Missing: amneziawg-tools
# Save the report (relative paths only: it is written inside /opt/kodachi/dashboard/hooks/)
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 run it at once (runs apt-get as root, no prompt: preview first)
deps-checker check-all --json | sudo deps-checker generate-script --execute
# Print the script only (without --execute nothing is ever run)
deps-checker check-all --json | deps-checker generate-script --dry-run
Dependency Reports
Generate comprehensive dependency documentation:
# Generate full dependency check report (written to /opt/kodachi/dashboard/hooks/deps-check-report.json)
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
jq '.summary' /opt/kodachi/dashboard/hooks/deps-check-report.json
# summary.exit_code is the exit code: 0 all required dependencies satisfied, 1 a missing or conflicting one
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: iproute2, sudo, procps, iputils-ping, coreutils, online-auth (openvpn, wireguard-tools, tun2socks, tor and the other clients are optional)
# 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
# Adds audio, security and disk tools (alsa, pulseaudio, lynis, rkhunter, cryptsetup, ...)
# 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. Reports success or failure from apt-get's exit status
# 4. Re-run deps-checker check to confirm the result
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 a custom dependency database (a directory of TOML manifests, used instead of the built-in one for that run)
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 Database | --db replaces the built-in database for that run with a directory of TOML manifests (a directory with no .toml manifest falls back to the built-in database) |
| Version Constraints | Minimum versions come from the dependency manifests |
| Platform Checks | Package names per distribution (Debian, Ubuntu, Fedora, Arch); install-missing runs on Debian-family systems only |
| Profiles | -p minimal or -p full (the default) per binary |
| SBOM | --sbom emits a CycloneDX JSON Software Bill of Materials |
| 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 | ~70KB (30 built-in TOML manifests) |
| 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 /opt/kodachi/dashboard/hooks/pre-install-deps-report.json
# Step 3: Review summary to identify critical issues
jq '.summary' /opt/kodachi/dashboard/hooks/pre-install-deps-report.json
# Expected: total_binaries, satisfied, with_missing, with_warnings and exit_code
# Step 4: Verify system integrity before proceeding
sudo 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.missing == 0'
# Expected: true if every required and optional package is 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: Link the binaries into the PATH with global-launcher
cd /opt/kodachi/dashboard/hooks && sudo ./global-launcher deploy
# Expected: Global symlinks deployed and verified
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: Check the minimal profile for a lightweight deployment
deps-checker check health-control -p minimal --json -o health-minimal-deps.json
# Expected: Core dependencies only (report saved under /opt/kodachi/dashboard/hooks/)
# 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
sudo 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 and disk tools 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 > install-deps.sh
# Expected: Bash script saved in the current directory (generate-script prints to stdout)
# Step 3: Generate zsh script for alternative shell environments
deps-checker check-all --json | deps-checker generate-script --shell zsh > 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
# create and add need an online-auth login first (sudo online-auth authenticate); run does not
workflow-manager create deps-gate
workflow-manager add deps-gate 'deps-checker check-all --strict'
workflow-manager run deps-gate
# 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)
# Expected: Numeric code (0 satisfied, 1 missing required, 2 version conflict, 3 unsupported distro)
sudo 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, Links the binaries into the PATH after dependency installation
- workflow-manager, Automated workflow integration for deployments
- Full CLI Reference: deps-checker commands