Operations hub
Infrastructure Tools
The plumbing behind Kodachi: workflows, logs, dependency checks, launchers, status, and online information. Use this area when operating or troubleshooting the stack: run workflows, inspect logs, validate dependencies, and monitor system status.
Workflows
Logs
Dependencies
Status
Service Infrastructure Backbone
Infrastructure binaries provide the operational foundation for Kodachi services: centralized logs, dependency validation, global deployment, workflow orchestration, and controlled online intelligence feeds.
Platform Operations
Ops
logs-hook, deps-checker, and global-launcher deliver system-wide observability, package readiness checks, and consistent binary deployment across installations.
13 Core Ops Commands
System-Wide Scope
Fast Deployment
Workflow and Information Layer
Flow
workflow-manager, online-info-switch, and conky-status add conditional automation, feed aggregation, and unified desktop telemetry with authentication-aware controls.
27 Automation Commands
Conditional Logic
Logged Runs
Documentation Navigation
Navigate the documentation:
- Install Binaries - Current APT, portable, and offline installation options
- CLI Reference - Complete command-line reference
Enterprise-Grade Service Infrastructure and Management
The infrastructure tools in Kodachi OS provide the foundational service layer for logging, dependency management, service deployment, and information control. These production-ready binaries ensure reliable system operation through centralized logging, automated deployment, and comprehensive dependency validation.
On the command line, every binary here prints its help with <binary> help as well as --help, and its help ends with the exit codes it returns. See Help and Exit Codes.
Core Architecture Principles - Verified
Centralized Management: Single point of control for logs, dependencies, and deployments
Zero Configuration: Embedded configurations with no external YAML dependencies
Service Orchestration: Automated deployment and verification of all binaries
Information Control: Secure management of online exposure and data feeds
Binary Categories and Requirements
Core Infrastructure Tools
| Binary | Primary Function | Commands | Requires Auth | Requires Sudo | Auto-Start |
|---|---|---|---|---|---|
| logs-hook | Centralized secure logging infrastructure | 4 | No | Only to maintain root-owned log files | Auto-integrated |
| deps-checker | Dependency validation and security auditing | 6 | No | Yes (install) | No |
| global-launcher | System-wide binary deployment manager | 3 | No | Yes (global) | Called by online-auth |
| workflow-manager | Batch command execution with conditional logic | 12 | Mixed (template changes) | No (steps carry their own sudo) | No |
| online-info-switch | Online information hub and RSS feeds | 11 | Mixed (paste only) | No | No |
| conky-status | Unified Conky desktop telemetry gateway | 4 | No | No | Auto (desktop watchdog) |
| kodachi-session-helper | Global emergency keyboard shortcut daemon in the user session | 3 | No | No | Session-driven |
Inter-Binary Dependencies Matrix
Binary Communication Flow
| Service | Calls These Binaries | Called By These Binaries |
|---|---|---|
| logs-hook | None | Kodachi's Rust binaries, through the shared logs-hook library |
| deps-checker | logs-hook | None |
| global-launcher | logs-hook | online-auth |
| workflow-manager | logs-hook | None (user-initiated) |
| online-info-switch | logs-hook, online-auth, health-control | None |
| conky-status | health-control, tor-switch, routing-switch, dns-switch, ip-fetch, online-info-switch, permission-guard, online-auth | Desktop Conky panels and scripts |
Critical Service Dependencies
| Dependency Type | Description | Affected Services |
|---|---|---|
| Logging Integration | All services automatically integrate logs-hook | Kodachi's Rust binaries, AI binaries such as ai-cmd and ai-monitor included |
| Deployment Chain | Services deployed by global-launcher | All Rust binaries |
| Authentication | Services requiring online-auth | online-info-switch (paste only), workflow-manager (template changes), and seven of the eight AI binaries (all but ai-discovery) for their non-read-only commands |
| System Health | Services using health-control | online-info-switch |
System Requirements and Permissions
Privilege Escalation Requirements
| Operation Type | Required Permissions | Affected Binaries |
|---|---|---|
| Log Maintenance | sudo for root-owned log files | logs-hook (rotate and wipe of logs written by root services) |
| Package Installation | sudo/root | deps-checker (apt-get operations) |
| Global Deployment | sudo/root | global-launcher (/opt/kodachi/dashboard/hooks/global-launcher) |
| Information Services | Standard user | online-info-switch (no command needs sudo) |
Service Integration Levels
| Integration Level | Method | Services |
|---|---|---|
| Embedded | Compiled into binary | logs-hook in all services |
| System-wide | Global symlinks | global-launcher deployments |
| Package Manager | APT/dpkg integration | deps-checker |
| Network APIs | HTTPS for every service except the ix.io paste endpoint, which only accepts plain HTTP | online-info-switch |
Key Capabilities Overview
Workflow Management (workflow-manager - 12 commands)
| Feature | Description |
|---|---|
| Template Creation | Create reusable workflow templates |
| Batch Execution | Execute multiple commands sequentially |
| Conditional Logic | Hybrid conditions: success/fail + pattern matching + JSON path |
| Pause Steps | Interactive pause points with user confirmation |
| State Tracking | Maintain workflow execution state |
| Run Logging | Every run logged as plain text through logs-hook |
| Failure Handling | Conditions and the kill policy decide what runs after a failed step; there are no automatic retries |
| Timeout Control | Configurable timeouts per step |
| Dry Run Mode | Test workflows without execution |
Centralized Logging (logs-hook - 4 commands)
| Feature | Description |
|---|---|
| Log Levels | Multiple levels: info, warn, error, debug, fatal |
| Script Categorization | Script-based log categorization |
| JSON Output | JSON format for automation |
| Log Rotation | Automatic rotation once a log passes 2,000 lines |
| Secure Wiping | Wipe overwrites a log with three random passes and a zero pass, then removes it |
| Selective Operations | Selective file operations |
| Auto-embedded | Linked into Kodachi's Rust binaries as a shared library |
| Centralized Storage | /opt/kodachi/dashboard/hooks/logs/ directory |
| Structured Format | Consistent logging format |
Dependency Management (deps-checker - 6 commands)
| Feature | Description |
|---|---|
| Single Binary Check | Dependency checking for individual binaries |
| System-wide Audit | Complete dependency audit across system |
| Profile-based Checking | Minimal/full profile options |
| Auto Installation | Automatic missing package installation |
| Script Generation | Generate install scripts for multiple shells |
| SBOM Generation | Software Bill of Materials generation |
| Database Support | External dependency database |
| Version Tracking | Track dependency versions |
| Security Audit | Integration with security auditing |
Binary Deployment (global-launcher - 3 commands)
| Feature | Description |
|---|---|
| Dynamic Discovery | Automatic binary discovery |
| Global Symlinks | Create symlinks in /usr/local/bin |
| Multi-language Support | Support for Rust binaries |
| Status Checking | Deployment status verification |
| Integrity Verification | Symlink integrity checks |
| Rollback | Rollback capabilities |
| Folder Containment | Execution folder containment |
| Permission Preservation | Maintain file permissions |
| Atomic Operations | Ensure operation atomicity |
Information Hub (online-info-switch - 11 commands)
| Feature | Description |
|---|---|
| Status Detection | Online/offline status detection |
| RSS Feeds | Security RSS feed aggregation |
| Paste Services | Public paste service integration |
| Proof of Freshness | News + blockchain verification |
| Crypto Prices | Cryptocurrency price monitoring |
| Wallet Balance | Bitcoin wallet balance checking |
| Transport | HTTPS for most services, validated against the system CA bundle (no certificate pinning) |
| Auth Verification | Authentication verification |
| Rate Limiting | Public price APIs can rate-limit lookups; there is no limiter of its own |
Desktop Telemetry (conky-status - 4 commands)
| Feature | Description |
|---|---|
| Unified Snapshot | One collection pass over the security, system, network and resource fields (snapshot) |
| Single Key Lookup | get <key> returns one snapshot path, legacy alias or user.<name> value |
| Batched Panels | panel <security|system|network|resources|gauges|all> returns one subset per Conky panel instead of one call per field |
| User Commands | user <path|init|list|run> manages and runs user-defined commands from a JSON registry |
| Cache Control | --refresh, --cached and --ttl <sec> govern reuse of the cached snapshot |
| Collection Limits | --max-parallel <n> and --timeout-ms <ms> bound each collection pass |
Common Workflows
Workflow Management
# Create workflow template
workflow-manager create my-workflow
# Add commands (comma-separated for multiple)
workflow-manager add my-workflow "sudo ip-fetch","online-auth check-login"
# Run workflow
sudo workflow-manager run my-workflow
# Test without execution
sudo workflow-manager run my-workflow --dry-run
# List all workflows
workflow-manager list
Logging Operations
# Log a message with specific level
logs-hook log --script "deployment" --level info "Service started"
# Rotate logs when they get large
sudo logs-hook maintenance rotate --file /opt/kodachi/dashboard/hooks/logs/health-control-log.log
# Secure wipe of old logs
sudo logs-hook maintenance wipe --all
Dependency Management
# Check dependencies for specific binary
deps-checker check health-control
# System-wide dependency audit
sudo deps-checker check-all --profile full
# Install missing dependencies
sudo deps-checker install-missing
# Generate installation script
deps-checker generate-script --shell bash > install_deps.sh
Service Deployment
# Deploy all binaries globally
cd /opt/kodachi/dashboard/hooks && sudo ./global-launcher deploy
# Verify deployment status
cd /opt/kodachi/dashboard/hooks && ./global-launcher verify
# Clean up deployments
cd /opt/kodachi/dashboard/hooks && sudo ./global-launcher cleanup
Information Services
# Check online status
online-info-switch status --json
# Get security RSS feeds
online-info-switch rss --max-items 10
# Proof of freshness
online-info-switch freshness --json
# Cryptocurrency prices
online-info-switch price all
Performance Metrics
| Metric | Value | Description |
|---|---|---|
| Total Commands | 43 | Across infrastructure binaries |
| Log Processing | 10,000 lines/sec | Maximum throughput |
| Deployment Time | < 5 seconds | For all binaries |
| Dependency Check | < 2 seconds | Per binary |
| Memory Usage | < 50MB | Combined services |
Infrastructure Architecture
Logging Architecture
Application → logs-hook (embedded) → Centralized Logs
↓
Log Rotation/Wiping
↓
Archive/Destruction
Dependency Flow
Binary Request → deps-checker → Package Database
↓
Validation/Installation
↓
System Packages
Deployment Pipeline
Source Binaries → global-launcher → Discovery
↓
Symlink Creation
↓
/usr/local/bin/
Service Management
Auto-Integration Features
| Feature | Implementation | Services |
|---|---|---|
| Logging | Shared logs-hook library | Kodachi's Rust binaries |
| Authentication | Runtime verification | online-info-switch (paste), workflow-manager (template changes), seven AI binaries |
| Deployment | System-wide symlinks | All services |
| Dependencies | Package manager integration | System-wide |
Maintenance Operations
# Daily maintenance routine
sudo logs-hook maintenance rotate --file /opt/kodachi/dashboard/hooks/logs/health-control-log.log
sudo deps-checker check-all
cd /opt/kodachi/dashboard/hooks && ./global-launcher verify
# Weekly maintenance
sudo logs-hook maintenance wipe --all
sudo deps-checker install-missing
Integration Points
The infrastructure tools integrate with:
| Integration Type | Components/Description |
|---|---|
| Kodachi's Rust Binaries | Through the shared logs-hook library |
| Package Managers | APT, dpkg for dependencies |
| File System | /usr/local/bin for deployments |
| Network Services | RSS feeds, APIs, paste services |
| Authentication | online-auth for secure operations |
Troubleshooting
Common Issues
| Issue | Solution | Prevention |
|---|---|---|
| Logs not rotating | Check disk space, permissions | Monitor log sizes |
| Dependencies missing | Run install-missing | Regular audits |
| Deployment fails | Check sudo permissions | Verify before deploy |
| RSS feeds empty | Check network, authentication | Test connectivity |
Diagnostic Commands
# Check logging system
logs-hook log --script test --level debug "Test message"
# Verify dependencies
deps-checker check-all --verbose
# Test deployment
cd /opt/kodachi/dashboard/hooks && sudo ./global-launcher deploy
# Check online services
online-info-switch status --verbose
Security Considerations
Important Security Notice
Infrastructure tools have system-wide impact. Always verify operations before execution, especially deployment and package installation commands.
Security Features
| Feature | Description |
|---|---|
| Embedded Configurations | No external config files to tamper |
| Execution Containment | Services operate within bounds |
| HTTPS | Network services use HTTPS where the remote service offers it |
| Audit Trails | Complete logging of operations |
| Permission Preservation | Maintain security boundaries |
Best Practices
| Practice | Description |
|---|---|
| Regular Audits | Check dependencies weekly |
| Log Management | Rotate and archive logs |
| Deployment Verification | Always verify after deploy |
| Network Security | Use authentication for online services |
| Backup Strategy | Maintain deployment rollback capability |
Advanced Features
Log Analysis
# Search logs for errors
grep -i error /opt/kodachi/dashboard/hooks/logs/*.log
# Error lines across all service logs (log files are plain text)
grep -F '[ERROR]' /opt/kodachi/dashboard/hooks/logs/*-log.log
# Real-time monitoring
tail -f /opt/kodachi/dashboard/hooks/logs/health-control-log.log
Dependency Profiles
| Profile | Use Case | Packages |
|---|---|---|
| Minimal | Core functionality | Essential only |
| Full | Complete feature set | All dependencies |
Deployment Strategies
| Strategy | Description | Use Case |
|---|---|---|
| Full Deploy | All binaries | Initial setup |
| Selective | Specific services | Updates |
| Rollback | Previous state | Recovery |
| Verify Only | Check without change | Audit |
System Information
| Component | Version | Build Date | License |
|---|---|---|---|
| logs-hook | 10.0.3 (build 75) | 2026 | Proprietary |
| deps-checker | 10.0.3 (build 75) | 2026 | Proprietary |
| global-launcher | 10.0.3 (build 75) | 2026 | Proprietary |
| workflow-manager | 10.0.3 (build 75) | 2026 | Proprietary |
| online-info-switch | 10.0.3 (build 75) | 2026 | Proprietary |
| conky-status | 10.0.3 (build 75) | 2026 | Proprietary |
| Documentation | 10.0.3 (build 75) | 2026 | © 2026 Kodachi OS |