Infrastructure guide
Global Launcher Guide
Deploy Kodachi binaries system-wide with safe symlinks and execution-folder containment. This guide walks the deploy, verify, and rollback flow used across installations.
Deployment
Symlinks
Rollback
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.8.4 (build 319) |
| Build Date | Not disclosed |
| 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