AI SUITE GUIDE

ai-scheduler Guide

A cron-based daemon that executes whitelisted Kodachi commands on a schedule. Only approved binaries can be scheduled, giving safe, automated task execution without opening a path to arbitrary command execution.

Cron daemon Whitelisted only Automation Task manager

ai-scheduler at a glance

ai-scheduler is a cron-based daemon that executes whitelisted Kodachi commands on a schedule. It provides safe, automated task execution: only approved binaries can be scheduled, preventing unauthorized command execution.

Version 9.8.4 5.5 MB binary Rust 1.82.0 Cron engine

Reference and verification

This is a scenario-first guide: operational workflows, real run order, and troubleshooting. For the full autogenerated command and flag catalog, use the ai-scheduler CLI Reference, or read the raw signer JSON.

SHA256 (v9.8.4): 312320c071286aa2f120d0e3ad358d9ffd3459c7e2e8d9b75b4caa9b146343f5

What ai-scheduler Does

ai-scheduler is a cron-based daemon that executes whitelisted Kodachi commands on a schedule. It provides safe, automated task execution, only approved binaries can be scheduled, preventing unauthorized command execution.

Key Capabilities

Feature	Description
Cron Scheduling	Standard cron expression support
Command Whitelist	Only approved Kodachi binaries can be scheduled
Task Management	Add, list, and remove scheduled tasks
Persistent State	Tasks survive daemon restarts

Whitelisted Commands

Only these binaries can be scheduled (security restriction):

Binary	Common Scheduled Operations
`dns-leak`	DNS leak testing
`tor-switch`	Tor circuit rotation
`health-control`	Security scoring, network checks
`integrity-check`	File integrity verification
`routing-switch`	Network routing checks
`dns-switch`	DNS configuration
`ip-fetch`	IP verification
`permission-guard`	Permission monitoring

Scenario 1: Automated Security Maintenance

Set up a complete automated security check pipeline across multiple security binaries.

# Step 1: Start the scheduler daemon
sudo ai-scheduler start

# Step 2: Schedule DNS leak checks every 6 hours
ai-scheduler add --name "dns-leak-6h" --command "dns-leak test" --cron "0 */6 * * *"

# Step 3: Schedule Tor status checks every 2 hours
ai-scheduler add --name "tor-status-2h" --command "tor-switch tor-status" --cron "0 */2 * * *"

# Step 4: Schedule daily security score check at midnight
ai-scheduler add --name "sec-score-daily" --command "health-control security-score" --cron "0 0 * * *"

# Step 5: Schedule network health check every 30 minutes
ai-scheduler add --name "net-check-30m" --command "health-control net-check" --cron "*/30 * * * *"

# Step 6: Schedule daily file integrity verification at 6 AM
ai-scheduler add --name "integrity-daily" --command "integrity-check check-all" --cron "0 6 * * *"

# Step 7: Schedule daily permission scan at 7 AM
ai-scheduler add --name "perms-daily" --command "permission-guard scan" --cron "0 7 * * *"

# Step 8: List all scheduled tasks to verify
ai-scheduler list

# Step 9: Verify JSON output for automation
ai-scheduler list --json

Cross-binary integration: ai-scheduler + dns-leak + tor-switch + health-control + integrity-check + permission-guard

Result: Continuous automated security monitoring without manual intervention.

Scenario 2: Automated AI Learning Pipeline

Automate the complete AI learning, optimization, and maintenance cycle using ai-scheduler.

# Step 1: Start the scheduler daemon
sudo ai-scheduler start

# Step 2: Schedule daily incremental learning at 2 AM
ai-scheduler add --name "ai-learn-daily" --command "ai-learner learn --incremental" --cron "0 2 * * *"

# Step 3: Schedule weekly database optimization (Sundays at 3 AM)
ai-scheduler add --name "ai-optimize-weekly" --command "ai-admin tune optimize" --cron "0 3 * * 0"

# Step 4: Schedule weekly index rebuild (Sundays at 4 AM)
ai-scheduler add --name "ai-rebuild-weekly" --command "ai-admin tune rebuild-index" --cron "0 4 * * 0"

# Step 5: Schedule monthly data cleanup (1st of month at 5 AM)
ai-scheduler add --name "ai-cleanup-monthly" --command "ai-admin tune cleanup --days 90" --cron "0 5 1 * *"

# Step 6: Verify all AI tasks are scheduled
ai-scheduler list

# Step 7: Get JSON output for verification
ai-scheduler list --json

Combined with ai-monitor for complete automation:

# Start real-time monitoring alongside scheduled tasks
sudo ai-monitor start --daemon

# Result:
# - ai-monitor: Real-time issue detection (every 30-60s)
# - ai-scheduler: Scheduled preventive maintenance (cron-based)
# - ai-learner: Automated learning pipeline
# - ai-admin: Automated database optimization

Cross-binary integration: ai-scheduler + ai-learner + ai-admin + ai-monitor

Scenario 3: Network-Focused Monitoring Schedule

Comprehensive network security monitoring schedule using all network-related binaries.

# Step 1: Start the scheduler
sudo ai-scheduler start

# Step 2: DNS leak detection every 6 hours
ai-scheduler add --name "dns-leak-6h" --command "dns-leak test" --cron "0 */6 * * *"

# Step 3: Network connectivity check every 30 minutes
ai-scheduler add --name "net-check-30m" --command "health-control net-check" --cron "*/30 * * * *"

# Step 4: Tor status monitoring every 2 hours
ai-scheduler add --name "tor-status-2h" --command "tor-switch tor-status" --cron "0 */2 * * *"

# Step 5: IP geolocation verification every 4 hours
ai-scheduler add --name "ip-fetch-4h" --command "ip-fetch" --cron "0 */4 * * *"

# Step 6: Routing status check every hour
ai-scheduler add --name "routing-hourly" --command "routing-switch status" --cron "0 * * * *"

# Step 7: DNS server status every 6 hours
ai-scheduler add --name "dns-status-6h" --command "dns-switch status" --cron "0 */6 * * *"

# Step 8: List all network monitoring tasks
ai-scheduler list

# Step 9: Export schedule in JSON format
ai-scheduler list --json

Network monitoring timeline:

Interval	Binary	Command	Purpose
Every 30 min	health-control	net-check	Connectivity verification
Every hour	routing-switch	status	Route configuration check
Every 2 hours	tor-switch	tor-status	Tor network status
Every 4 hours	ip-fetch	(default)	IP/geolocation verification
Every 6 hours	dns-leak	test	DNS leak detection
Every 6 hours	dns-switch	status	DNS server verification

Cross-binary integration: ai-scheduler + dns-leak + health-control + tor-switch + ip-fetch + routing-switch + dns-switch

Scenario 4: Managing Scheduled Tasks

Complete task lifecycle management: list, review, remove, and verify.

# Step 1: List all scheduled tasks
ai-scheduler list

# Example output:
# ID  Name              Command                       Cron
# 1   dns-leak-6h       dns-leak test                 0 */6 * * *
# 2   tor-status-2h     tor-switch tor-status         0 */2 * * *
# 3   sec-score-daily   health-control security-score      0 0 * * *
# 4   net-check-30m     health-control net-check      */30 * * * *
# 5   integrity-daily   integrity-check check-all        0 6 * * *

# Step 2: Review tasks and decide which to remove
# Let's say task 4 (net-check-30m) is too frequent

# Step 3: Remove task by ID
ai-scheduler remove 4

# Step 4: List again to verify removal
ai-scheduler list

# Output now shows:
# ID  Name              Command                       Cron
# 1   dns-leak-6h       dns-leak test                 0 */6 * * *
# 2   tor-status-2h     tor-switch tor-status         0 */2 * * *
# 3   sec-score-daily   health-control security-score      0 0 * * *
# 5   integrity-daily   integrity-check check-all        0 6 * * *

# Step 5: Get JSON output for scripting/automation
ai-scheduler list --json

# Step 6: Remove with JSON output for verification
ai-scheduler remove 5 --json

Task management workflow:

List - Review all scheduled tasks
Analyze - Determine which tasks need adjustment
Remove - Delete tasks by ID
Verify - List again to confirm changes
JSON Export - Use --json for scripting integration

Use cases:

Remove redundant/overlapping tasks
Clean up after testing schedules
Adjust task frequency by removing and re-adding
Export schedule configuration for backup
Script-based task management with JSON output

Scenario 5: Complete Production Schedule

Enterprise-grade production schedule combining security monitoring, AI learning, and system maintenance.

# Step 1: Start the scheduler daemon
sudo ai-scheduler start

# === SECURITY MONITORING ===
# DNS leak detection every 6 hours
ai-scheduler add --name "dns-leak-6h" --command "dns-leak test" --cron "0 */6 * * *"

# Tor status check every 2 hours
ai-scheduler add --name "tor-status-2h" --command "tor-switch tor-status" --cron "0 */2 * * *"

# Network health check every 30 minutes
ai-scheduler add --name "net-check-30m" --command "health-control net-check" --cron "*/30 * * * *"

# Daily security score at midnight
ai-scheduler add --name "sec-score-daily" --command "health-control security-score" --cron "0 0 * * *"

# File integrity verification at 6 AM
ai-scheduler add --name "integrity-6am" --command "integrity-check check-all" --cron "0 6 * * *"

# Permission monitoring at 7 AM
ai-scheduler add --name "perms-7am" --command "permission-guard scan" --cron "0 7 * * *"

# IP verification every 4 hours
ai-scheduler add --name "ip-verify-4h" --command "ip-fetch" --cron "0 */4 * * *"

# Routing status check hourly
ai-scheduler add --name "routing-hourly" --command "routing-switch status" --cron "0 * * * *"

# DNS server status every 6 hours
ai-scheduler add --name "dns-status-6h" --command "dns-switch status" --cron "0 */6 * * *"

# === AI LEARNING PIPELINE ===
# Daily incremental learning at 2 AM
ai-scheduler add --name "ai-learn-2am" --command "ai-learner learn --incremental" --cron "0 2 * * *"

# === DATABASE MAINTENANCE ===
# Weekly database optimization (Sundays at 4 AM)
ai-scheduler add --name "db-optimize-sun" --command "ai-admin tune optimize" --cron "0 4 * * 0"

# Weekly index rebuild (Sundays at 5 AM)
ai-scheduler add --name "index-rebuild-sun" --command "ai-admin tune rebuild-index" --cron "0 5 * * 0"

# Monthly data cleanup (1st of month at 3 AM)
ai-scheduler add --name "cleanup-monthly" --command "ai-admin tune cleanup --days 90" --cron "0 3 1 * *"

# Step 2: Verify complete production schedule
ai-scheduler list

# Step 3: Export schedule configuration
ai-scheduler list --json

Daily Timeline

Time	Task	Binary	Purpose
Every 30 min	Network check	health-control	Connectivity monitoring
Every hour	Routing status	routing-switch	Route verification
Every 2 hours	Tor status	tor-switch	Circuit monitoring
Every 4 hours	IP verification	ip-fetch	Geolocation check
Every 6 hours	DNS leak test	dns-leak	Leak prevention
Every 6 hours	DNS status	dns-switch	DNS server check
Midnight	Security score	health-control	Daily baseline
2:00 AM	AI learning	ai-learner	Feedback processing
3:00 AM (1st)	Data cleanup	ai-admin	Storage management
4:00 AM (Sun)	DB optimize	ai-admin	Performance tuning
5:00 AM (Sun)	Index rebuild	ai-admin	Search optimization
6:00 AM	Integrity check	integrity-check	File verification
7:00 AM	Permission scan	permission-guard	Permission monitoring

Cron Expression Reference

Expression	Meaning	Use Case
`/30 * * *`	Every 30 minutes	High-frequency monitoring
`0 * * * *`	Every hour	Regular status checks
`0 /2 * *`	Every 2 hours	Medium-frequency tasks
`0 /4 * *`	Every 4 hours	Moderate monitoring
`0 /6 * *`	Every 6 hours	Low-frequency checks
`0 0 * * *`	Daily at midnight	Daily baselines
`0 2 * * *`	Daily at 2 AM	Automated learning
`0 6 * * *`	Daily at 6 AM	Morning verification
`0 4 * * 0`	Weekly (Sunday 4 AM)	Weekly maintenance
`0 3 1 * *`	Monthly (1st at 3 AM)	Monthly cleanup

Cross-binary integration: ai-scheduler + dns-leak + tor-switch + health-control + integrity-check + permission-guard + ip-fetch + routing-switch + dns-switch + ai-learner + ai-admin

Scenario 6: Debugging Scheduled Tasks

Test and verify scheduled tasks execute correctly using foreground mode.

# Step 1: Stop any running scheduler daemon
sudo pkill ai-scheduler

# Step 2: Add test tasks for debugging
ai-scheduler add --name "test-dns" --command "dns-leak test" --cron "*/5 * * * *"
ai-scheduler add --name "test-health" --command "health-control net-check" --cron "*/5 * * * *"

# Step 3: Start scheduler in foreground mode (see live execution)
sudo ai-scheduler start --foreground

# Output shows:
# [2026-02-09 10:00:00] Starting scheduler in foreground mode
# [2026-02-09 10:00:00] Loaded 2 scheduled tasks
# [2026-02-09 10:05:00] Executing task 'test-dns': dns-leak test
# [2026-02-09 10:05:03] Task 'test-dns' completed successfully
# [2026-02-09 10:05:03] Executing task 'test-health': health-control net-check
# [2026-02-09 10:05:05] Task 'test-health' completed successfully

# Step 4: Start with JSON output for automated testing
sudo ai-scheduler start --foreground --json

# JSON output example:
# {"timestamp":"2026-02-09T10:05:00Z","event":"task_start","task_id":1,"task_name":"test-dns","command":"dns-leak test"}
# {"timestamp":"2026-02-09T10:05:03Z","event":"task_complete","task_id":1,"task_name":"test-dns","exit_code":0,"duration_ms":3024}

# Step 5: Test daemon mode with JSON logging
sudo ai-scheduler start --json

# Step 6: Verify tasks in separate terminal
ai-scheduler list

# Step 7: Clean up test tasks
ai-scheduler remove 1
ai-scheduler remove 2

Debugging workflow:

Step	Command	Purpose
1	`--foreground`	See live task execution in terminal
2	`--foreground --json`	Structured output for parsing
3	`--json`	Daemon mode with JSON logging
4	`list`	Verify tasks are loaded
5	`remove`	Clean up test tasks

Common debugging scenarios:

# Scenario A: Verify cron expression fires correctly
ai-scheduler add --name "debug-test" --command "health-control net-check" --cron "*/1 * * * *"
sudo ai-scheduler start --foreground
# Watch for task execution every minute

# Scenario B: Test task with JSON output for automation
sudo ai-scheduler start --foreground --json | tee /tmp/scheduler-debug.log
# Parse JSON logs for automated testing

# Scenario C: Verify task removal works
ai-scheduler list
ai-scheduler remove 1 --json
# Check JSON response confirms deletion

Cross-binary integration: ai-scheduler

Automated Security Monitoring, Scheduler + Monitor pipeline
Automated Learning Pipeline, AI learning automation
ai-monitor, Real-time monitoring (complements scheduling)
ai-learner, Schedule learning cycles
ai-admin, Schedule database maintenance
Full CLI Reference: ai-scheduler commands

Quick Command Summary

Based on actual ai-scheduler -e output:

Daemon Control

sudo ai-scheduler start                    # Start as daemon
sudo ai-scheduler start --foreground       # Start in foreground (debugging)
sudo ai-scheduler start --foreground --json # Foreground with JSON output
sudo ai-scheduler start --json             # Daemon with JSON logging

Schedule Management

# Add tasks
ai-scheduler add --name "daily-check" --command "health-control net-check" --cron "0 8 * * *"
ai-scheduler add --name "hourly-tor" --command "tor-switch tor-status" --cron "0 * * * *"
ai-scheduler add --name "dns-check" --command "dns-leak test" --cron "*/30 * * * *" --json

# List tasks
ai-scheduler list
ai-scheduler list --json

# Remove tasks
ai-scheduler remove 1
ai-scheduler remove 2 --json

Whitelisted Commands

Only these binaries can be scheduled (security restriction):

dns-leak
tor-switch
health-control
integrity-check
routing-switch
dns-switch
ip-fetch
permission-guard

Troubleshooting

Problem	Cause	Solution
Task not executing	Command not in whitelist	Only whitelisted binaries above can be scheduled
"Invalid cron expression"	Syntax error in schedule	Verify cron format (5 fields: min hour day month weekday)
Daemon won't start	Port conflict or permissions	Run with `--foreground` to see errors; use `sudo`
Missed scheduled tasks	Daemon was stopped during scheduled time	Tasks don't retroactively run; restart daemon and wait for next cycle
Task runs but fails	Binary not found or wrong arguments	Test command manually first before scheduling

ai-scheduler Guide

ai-scheduler at a glance

What ai-scheduler Does

Key Capabilities

Whitelisted Commands

Scenario 1: Automated Security Maintenance

Scenario 2: Automated AI Learning Pipeline

Scenario 3: Network-Focused Monitoring Schedule

Scenario 4: Managing Scheduled Tasks

Scenario 5: Complete Production Schedule

Daily Timeline

Cron Expression Reference

Scenario 6: Debugging Scheduled Tasks

Related Workflows

Quick Command Summary

Daemon Control

Schedule Management

Whitelisted Commands

Troubleshooting