Global Launcher
INFRASTRUCTURE TOOL
Operate Kodachi support services with confidence.
These guides cover workflows, logs, launchers, dependency checks, and status plumbing used by the rest of Kodachi.
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 | global-launcher |
| Version | 9.0.1 |
| Build Date | REDACTED-BUILD-TIME |
| Rust Version | rustc 1.96.0 (ac68faa20 2026-05-25) |
| File Size | 1.9MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Infrastructure & Management |
| Description | Global launcher for Kodachi dashboard binaries with execution folder containment |
| JSON Data | View Raw JSON |
SHA256 Checksum
Key Features
Symlink Deployment Management
| Feature | Description |
|---|---|
| Symlink Deployment | Creates system-wide symlinks for all dashboard binaries |
| Execution Containment | Enforces folder-based isolation for all binaries |
| Deployment Verification | Verifies symlink integrity and target binary health |
| Hash Reporting | Generates SHA256 hash reports for binary integrity tracking |
Why Global Launcher is Essential
| Benefit | Description |
|---|---|
| Security Isolation | Binaries execute within their designated folder context |
| Consistent Deployment | All binaries deployed uniformly via symlinks |
| Deployment Integrity | SHA256 hashes track binary versions and detect tampering |
| Global Access | Deployed binaries are accessible from anywhere in the PATH |
Scope Clarification
global-launcher manages symlink deployment only (deploy / verify / cleanup). It does NOT start, stop, or restart services. For daemon lifecycle use the respective service's own subcommands (e.g., online-auth start-heartbeat, permission-guard --daemon watch, systemctl).
TL;DR - Essential Commands
# Run from the hooks directory
cd /opt/kodachi/dashboard/hooks
# Deploy global symlinks for all dashboard binaries
sudo ./global-launcher deploy
# Verify deployed symlinks are working
./global-launcher verify
# Remove all deployed symlinks
sudo ./global-launcher cleanup
Understanding Service Deployment
Execution Folder Containment
Global Launcher enforces a critical security principle - services can only write to their execution directory:
# Deploy service with containment
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher deploy
# Service structure:
# dashboard/hooks/
# ├── ip-fetch/ # Execution directory
# │ ├── ip-fetch # Binary
# │ ├── temp/ # Temporary files
# │ ├── cache/ # Cache data
# │ └── output/ # Results
Security Benefit: Services cannot write to system directories or other service folders.
Deploying Services
# Deploy all dashboard binaries as global symlinks
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher deploy
# Deploy with JSON output
sudo ./global-launcher deploy --json
# Force deployment even if binaries exist
sudo ./global-launcher deploy --force
# Deploy without verification
sudo ./global-launcher deploy --no-verify
Service Verification
# Verify all deployed symlinks
cd /opt/kodachi/dashboard/hooks
./global-launcher verify
# Verify with detailed information
./global-launcher verify --detailed
# Verify with JSON output
./global-launcher verify --json
# What it checks:
# <i class="fas fa-check" style="color: #4CAF50;"></i> Symlinks exist and are valid
# <i class="fas fa-check" style="color: #4CAF50;"></i> Target binaries are executable
# <i class="fas fa-check" style="color: #4CAF50;"></i> Permissions are correct
Cleanup Operations
# Remove all deployed symlinks
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher cleanup
# Cleanup without confirmation prompt
sudo ./global-launcher cleanup --yes
# Cleanup with JSON output
sudo ./global-launcher cleanup --json
Deployment Workflow
# Typical deployment workflow
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher deploy # Deploy symlinks
./global-launcher verify # Verify deployment
health-control security-status # Test a deployed binary
# Re-deployment workflow
sudo ./global-launcher cleanup --yes # Remove existing
sudo ./global-launcher deploy --force # Force new deployment
Important Options
# Override target user for deployment
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher deploy --user-override kodachi
# Set custom timeout (default: 600 seconds)
./global-launcher verify --timeout 300
# Enable verbose output
./global-launcher verify --verbose
# Disable colored output
NO_COLOR=1 ./global-launcher verify
Exit Codes
Global Launcher uses specific exit codes for different scenarios:
0 Success
1 General error
2 Invalid arguments
3 Permission denied
4 Binary not found
5 Directory not found
6 Timeout
7 Deployment error
8 Execution error
9 Validation error
10 Security violation
Environment Variables
# Set custom hooks directory
KODACHI_BASE_DIR=/custom/path ./global-launcher verify
# Enable debug logging
RUST_LOG=debug ./global-launcher deploy
# Disable colored output
NO_COLOR=1 ./global-launcher verify
JSON Output Examples
# Get deployment status in JSON
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher deploy --json
# Pretty-printed JSON output
./global-launcher verify --json-pretty
# Parse JSON with jq
./global-launcher verify --json | jq '.data.verified_symlinks[]'
What Global Launcher Actually Does
Global Launcher creates system-wide symlinks for dashboard binaries:
# After deployment, binaries are available globally:
health-control net-check-http # Works from anywhere
ip-fetch fetch # No need for full path
dns-switch status # Accessible system-wide
# (Binaries become available in PATH via symlinks created by global-launcher)
# Symlinks are created in system PATH
# Typically /usr/local/bin or similar
Automatic Integration with Online-Auth
Global Launcher deployment is automatically handled by the online-auth service during authentication.
How It Works
When you authenticate:
sudo online-auth authenticate
# Global-launcher automatically:
# → Deploys all dashboard binaries
# → Creates system-wide symlinks
# → Verifies deployment success
Manual Deployment Scenarios
| Scenario | Description |
|---|---|
| Troubleshooting | Debugging deployment issues |
| Testing | Running binaries without authentication |
| Recovery | Fixing system problems |
| Customization | Non-standard deployment paths |
Note
For normal usage, authentication handles everything automatically.
Command Reference
global-launcher exposes exactly three subcommands. All other service-lifecycle operations belong to the respective service binaries.
| Subcommand | Description |
|---|---|
deploy |
Create symlinks in the global bin directory for all discovered dashboard binaries |
verify |
Check that all deployed symlinks resolve to valid, executable targets |
cleanup |
Remove all deployed symlinks |
For the full flag catalog, see the auto-generated command reference.
Security Notes
Important Security Practices:
| Practice | Description |
|---|---|
| Deployment Verification | Always verify deployments after installation |
| Containment Checks | Regularly check for containment violations |
| Resource Monitoring | Monitor service resource usage |
| Process Cleanup | Clean up orphaned processes regularly |
| Log Review | Review service logs for anomalies |
Performance
| Metric | Value |
|---|---|
| Deploy Time | < 2 seconds per service |
| Memory Usage | ~20MB for launcher |
| CPU Usage | < 5% during deployment |
| Verification Speed | < 1 second per service |
| Cleanup Time | 2-5 seconds total |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: Initial System Binary Deployment
First-time deployment after fresh install or when binaries are updated.
# Step 1: Check system dependencies first
cd /opt/kodachi/dashboard/hooks/rust/deps-checker
cargo run -- check
# Expected: Lists all required system packages and their status
# Step 2: Deploy global symlinks for all dashboard binaries
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher deploy
# Expected: Creates symlinks in /usr/local/bin for all discovered binaries
# Step 3: Verify deployment was successful
./global-launcher verify --detailed
# Expected: Reports on symlink status, target binaries, and permissions
# Step 4: Save SHA256 hash report for integrity tracking
./global-launcher verify --save-hashes
# Expected: Creates verification-hashes.json in hooks/results/ with all binary hashes
# Step 5: Test a deployed binary works globally
health-control security-status
# Expected: Executes health-control from anywhere, shows system status
# Step 6: Verify binary integrity with saved hashes
cd /opt/kodachi/dashboard/hooks/rust/integrity-check
cargo run -- verify --timeout 300
# Expected: Verifies signatures and integrity of all deployed binaries
Cross-binary workflow: global-launcher + deps-checker + integrity-check + health-control
When to run: After fresh install, after binary updates, or when troubleshooting deployment issues. Or Automate this with workflow-manager for consistent deployment.
Scenario 2: Post-Update Redeployment with Hash Verification
When dashboard binaries are updated, redeploy and compare hashes to verify changes.
# Step 1: Save current hash baseline before update
cd /opt/kodachi/dashboard/hooks
./global-launcher verify --save-hashes
# Expected: Creates verification-hashes.json with pre-update binary hashes
# Step 2: Update binaries (example: rebuilding Rust services)
cd /opt/kodachi/dashboard/hooks/rust/health-control
cargo build --release
# Expected: New binary built in target/release/
# Step 3: Deploy with force to replace existing symlinks
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher deploy --force --save-hashes
# Expected: Overwrites symlinks, creates deployment-hashes.json with new hashes
# Step 4: Compare old and new hashes to detect changes
diff hooks/results/verification-hashes.json hooks/results/deployment-hashes.json
# Expected: Shows which binaries have changed SHA256 hashes
# Step 5: Verify new deployment integrity
cd /opt/kodachi/dashboard/hooks/rust/integrity-check
cargo run -- verify --timeout 300
# Expected: Verifies signatures and integrity of updated binaries
# Step 6: Test updated binary works correctly
health-control net-check-http
# Expected: Network check completes successfully with new binary
Cross-binary workflow: global-launcher + integrity-check + health-control
When to run: After building updated binaries, before deploying to production, or when tracking version changes.
Scenario 3: Force Redeployment and Backup
Clean redeployment when symlinks are broken or system is misconfigured.
# Step 1: Save current deployment state for backup
cd /opt/kodachi/dashboard/hooks
./global-launcher verify --detailed --json > /tmp/deployment-backup.json
# Expected: JSON report with all current symlink states saved
# Step 2: Remove all existing symlinks cleanly
sudo ./global-launcher cleanup --yes
# Expected: Removes all symlinks from /usr/local/bin, reports count
# Step 3: Verify cleanup was complete
./global-launcher verify
# Expected: Reports no symlinks found or all missing
# Step 4: Force fresh deployment with verification
sudo ./global-launcher deploy --force --save-hashes
# Expected: Creates new symlinks, generates deployment-hashes.json
# Step 5: Verify new deployment is healthy
./global-launcher verify --detailed
# Expected: All symlinks valid, targets executable, permissions correct
# Step 6: Run integrity check on redeployed binaries
cd /opt/kodachi/dashboard/hooks/rust/integrity-check
cargo run -- verify --timeout 300
# Expected: All signatures verified, no integrity violations
# Step 7: Test critical binaries work correctly
health-control security-status
ip-fetch fetch
dns-switch status
# Expected: All binaries execute successfully from global paths
Cross-binary workflow: global-launcher + integrity-check + health-control + ip-fetch + dns-switch
When to run: When symlinks are broken, after system configuration changes, or when recovering from deployment errors.
Scenario 4: Using Global Binaries Post-Deployment
Once deployed, binaries work from any directory without full paths.
# Step 1: Verify deployment status from any location
cd ~
cd /opt/kodachi/dashboard/hooks && ./global-launcher verify
# Expected: Reports on symlink status from home directory
# Step 2: Run health-control from anywhere
health-control security-status
# Expected: Executes in hooks directory context, shows system health
# Step 3: Fetch IP information globally
ip-fetch fetch
# Expected: Retrieves IP geolocation data, creates output in hooks/results/
# Step 4: Check network connectivity
health-control net-check-http
# Expected: Tests network connectivity, reports DNS and internet status
# Step 5: View DNS configuration
dns-switch status
# Expected: Shows current DNS servers and configuration
# Step 6: Run Tor status check
tor-switch tor-status
# Expected: Reports Tor circuit status and exit node information
# Step 7: Get detailed binary info with JSON output
cd /opt/kodachi/dashboard/hooks && ./global-launcher verify --detailed --json | jq '.data.verified_symlinks[] | {name, target, source_binary_hash}'
# Expected: JSON output with binary names, paths, and SHA256 hashes
Cross-binary workflow: global-launcher + health-control + ip-fetch + dns-switch + tor-switch
When to run: Daily operations, system monitoring, or when testing global binary access. Or Automate this with workflow-manager for scheduled health checks.
Scenario 5: Binary Removal and Cleanup
Remove global binary access when troubleshooting or before system changes.
# Step 1: Save deployment state before removal
cd /opt/kodachi/dashboard/hooks
./global-launcher verify --detailed --save-hashes
# Expected: Creates verification-hashes.json with current binary states
# Step 2: Check system dependencies before cleanup
cd /opt/kodachi/dashboard/hooks/rust/deps-checker
cargo run -- check
# Expected: Lists dependencies that may be affected by binary removal
# Step 3: Remove all deployed symlinks
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher cleanup --yes
# Expected: Removes all symlinks, reports total count removed
# Step 4: Verify cleanup completed successfully
./global-launcher verify
# Expected: No symlinks found, all binaries inaccessible from PATH
# Step 5: Confirm binaries no longer work globally
health-control security-status 2>&1 || echo "Binary not in PATH (expected)"
# Expected: Command not found error (binaries removed from global access)
# Step 6: Binaries still work from local directory
cd /opt/kodachi/dashboard/hooks
./health-control security-status
# Expected: Works when executed from hooks directory with ./ prefix
# Step 7: Redeploy if cleanup was for troubleshooting
sudo ./global-launcher deploy --force
# Expected: Fresh deployment with new symlinks created
Cross-binary workflow: global-launcher + deps-checker + health-control
When to run: Before system maintenance, when troubleshooting deployment issues, or when testing local-only binary execution.
Related Workflows
- Health Control — System health monitoring and security scoring
- IP Fetch — IP geolocation and network information
- DNS Switch — DNS server management and leak prevention
- Tor Switch — Tor network management and routing
- Integrity Check — Binary signature verification and system integrity
- Deps Checker — System dependency verification
- Full CLI Reference: global-launcher commands