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 | 10.0.3 (build 75) |
| Build Date | Not disclosed |
| Rust Version | rustc 1.98.0 (88d9e12ae 2026-08-18) |
| File Size | 2.1MB |
| 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
ba47dbee8d65fd4e2c51c1a06388279529ead27d9fa4c395a3c54df517be3a30
Key Features
Symlink Deployment Management
| Feature | Description |
|---|---|
| Symlink Deployment | Creates system-wide symlinks for all dashboard binaries |
| Execution Containment | Runs every binary from the hooks directory with KODACHI_BASE_DIR set, so its files stay under that folder |
| Deployment Verification | Verifies each symlink resolves, its target is executable and the source binary exists |
| 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 keeps every binary in its execution folder: each /usr/local/bin symlink points to the launcher, which re-enters the hooks directory, sets KODACHI_BASE_DIR and runs the real binary there:
# Deploy service with containment
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher deploy
# Layout (one shared hooks directory, not one folder per binary):
# /opt/kodachi/dashboard/hooks/
# ├── ip-fetch # Binary (/usr/local/bin/ip-fetch links to the launcher)
# ├── global-launcher # The launcher every symlink points to
# ├── logs/ # <binary>-log.log files
# ├── results/ # Saved results, for example ip_history.json
# └── tmp/ # Temporary files
Security Benefit: Binaries keep their logs, results and temporary files in one known folder instead of the caller's current directory. This is a working-directory convention, not a sandbox: binaries run with sudo still change system settings such as firewall rules and DNS.
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:
# ✓ Symlinks exist and point to the launcher
# ✓ Targets are executable
# ✓ Source binaries exist in the hooks directory
Cleanup Operations
# Remove all deployed symlinks
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher cleanup
# --yes is accepted but has no effect: cleanup never prompts
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
sudo 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
# --user-override is accepted but has no effect today
cd /opt/kodachi/dashboard/hooks
sudo ./global-launcher deploy --user-override kodachi
# --timeout has no effect on the launcher; GLOBAL_LAUNCHER_TIMEOUT (default 900 seconds) bounds binaries run through a symlink
GLOBAL_LAUNCHER_TIMEOUT=300 health-control security-score
# Enable verbose output
./global-launcher verify --verbose
# Disable colored output
NO_COLOR=1 ./global-launcher verify
Exit Codes
Global Launcher's help ends with these exit codes. After it runs another binary through its symlink, it returns that binary's own exit code unchanged:
0 Success
1 General error, including a binary or directory that was not found
2 Invalid arguments
6 Timeout: the launched binary did not finish in time
7 Deployment or verification failure (recovery: sudo ./global-launcher cleanup && sudo ./global-launcher deploy)
137 The launched binary was killed by a signal
Environment Variables
# Set custom hooks directory
KODACHI_BASE_DIR=/custom/path ./global-launcher verify
# Deploy the symlinks into another directory (set it again for verify and cleanup)
GLOBAL_BIN_DIR="$HOME/.local/bin" ./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:
sudo 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
# /usr/local/bin by default (GLOBAL_BIN_DIR changes it)
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
# online-auth checks the deployment and, when it is not current, runs global-launcher deploy, which:
# → 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
deps-checker check-all
# (deps-checker is itself a deployed binary; on a fresh system run it as ./deps-checker from the hooks directory)
# 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 symlink status, targets and source binaries
# 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
sudo health-control security-status
# Expected: Executes health-control from anywhere, shows system status
# Step 6: Verify binary signatures and integrity
cd /opt/kodachi/dashboard/hooks
sudo integrity-check check-all --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 the binaries (they ship in the kodachi-hooks-core package)
sudo apt update
sudo apt install --only-upgrade kodachi-hooks-core
# Expected: Updated binaries in /opt/kodachi/dashboard/hooks/
# 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 results/verification-hashes.json results/deployment-hashes.json
# Expected: Shows which binaries have changed SHA256 hashes
# Step 5: Verify new deployment integrity
cd /opt/kodachi/dashboard/hooks
sudo integrity-check check-all --timeout 300
# Expected: Verifies signatures and integrity of updated binaries
# Step 6: Test updated binary works correctly
sudo 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 updating 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, source binaries present
# Step 6: Run integrity check on redeployed binaries
cd /opt/kodachi/dashboard/hooks
sudo integrity-check check-all --timeout 300
# Expected: All signatures verified, no integrity violations
# Step 7: Test critical binaries work correctly
sudo 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
sudo 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
sudo 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: Tor service status (PID, memory, uptime)
# 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_path, 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 a workflow-manager template run from cron or a systemd timer (workflow-manager does not schedule).
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
deps-checker check-all
# (run before cleanup: afterwards it is only reachable as ./deps-checker in the hooks directory)
# 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
sudo ./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