agentctl

Like pm2/supervisord, but purpose-built for managing local AI agent daemons.

Running multiple AI agents locally means juggling launchd/systemd services, scattered logs, duplicate auth configs, and manual health checks. agentctl unifies all of this into one CLI.

Features

• Process Management — start/stop/restart agents via launchd (macOS), systemd (Linux), or raw process
• Unified Auth Pool — centralized credential store, sync to all agents with one command
• Log Aggregation — tail logs from all agents, color-coded and interleaved
• Health Monitoring — process alive checks + HTTP endpoint probing
• Token Usage Tracking — aggregate API usage and cost estimates across agents
• Continuous Monitoring — daemon mode with Telegram alerts on failures
• Auto-Discovery — agentctl init scans for existing launchd services and auth configs
• Bot Setup — configure Telegram bots (commands, description, webhook) from CLI

Install

cargo install --path .

Or build from source:

git clone https://github.com/tonitangpotato/agentctl.git
cd agentctl
cargo build --release
# Binary at target/release/agentctl

Quick Start

# Auto-discover existing agents and auth configs
agentctl init

# Check status of all agents
agentctl status

# View interleaved logs
agentctl logs --all -f

# Switch all agents to a different credential
agentctl auth use anthropic:default

# Run health checks
agentctl health

# Start continuous monitoring with Telegram alerts
agentctl monitor --daemon

Usage

agentctl — AI Agent Process Manager

PROCESS MANAGEMENT:
    agentctl start <agent>          Start an agent daemon
    agentctl stop <agent>           Stop an agent daemon
    agentctl restart <agent>        Restart an agent daemon
    agentctl status [agent]         Show status of one or all agents
    agentctl list                   List all registered agents

AUTH MANAGEMENT:
    agentctl auth list              Show all credentials and which agents use them
    agentctl auth add <name>        Add a new credential to the pool
    agentctl auth use <name>        Switch all agents to a credential
    agentctl auth test [name]       Test credential(s) against provider APIs
    agentctl auth sync              Push pool credentials to all agent configs
    agentctl auth import <path>     Import from existing auth-profiles.json

LOG MANAGEMENT:
    agentctl logs <agent>           Show recent logs
    agentctl logs <agent> -f        Follow/tail logs in real-time
    agentctl logs --all             Interleave all agent logs (color-coded)

MONITORING:
    agentctl health [agent]         Check agent health endpoints
    agentctl usage [agent]          Show API token usage and cost estimates
    agentctl monitor --daemon       Continuous monitoring with alerts
    agentctl monitor --once         Single health check pass (for cron)

CONFIGURATION:
    agentctl init                   Interactive setup (auto-discover agents)
    agentctl config show            Print resolved config
    agentctl config edit            Open config in $EDITOR

BOT SETUP:
    agentctl bot setup --token <t>  Configure a Telegram bot

Configuration

Config lives at ~/.agentctl/config.toml:

[settings]
default_platform = "launchd"

[[agents]]
name = "rustclaw"
kind = "launchd"
plist = "com.rustclaw.agent"
log_out = "~/.rustclaw/logs/rustclaw.log"
health_endpoint = "http://localhost:8081/api/health"
usage_endpoint = "http://localhost:8081/api/tokens"

  [agents.auth]
  format = "auth-profiles-json"
  path = "~/.rustclaw/auth-profiles.json"
  reload = "signal:SIGHUP"

Auth pool at ~/.agentctl/auth.toml:

[pool."anthropic:default"]
provider = "anthropic"
type = "token"
token = "sk-ant-..."

[defaults]
anthropic = "anthropic:default"

Example Output

$ agentctl status
 AGENT       STATUS    PID    UPTIME     CPU   MEM
 rustclaw    ● run     1234   3d 2h      0.1%  45MB
 openclaw    ● run     5678   1d 14h     0.3%  120MB

$ agentctl health
 AGENT       PROCESS   ENDPOINT          LATENCY   LAST CHECK
 rustclaw    ✅ alive   ✅ 200 OK         12ms      just now
 openclaw    ✅ alive   ✅ 200 OK         8ms       just now

$ agentctl usage --period 24h
 AGENT       REQUESTS   INPUT TOK   OUTPUT TOK   COST (est)
 rustclaw    47         125,340     43,210       $2.84
 openclaw    312        890,100     234,500      $18.42

Architecture

agentctl CLI
    ├── Agent Registry (~/.agentctl/config.toml)
    ├── Auth Pool (~/.agentctl/auth.toml)
    └── Platform Adapters
        ├── launchd (macOS)
        ├── systemd (Linux)
        └── process (manual/dev)

~5,700 lines of Rust. 38 tests. Zero unsafe.

License

Dual-licensed under:

• AGPL-3.0 — Free for open-source use (LICENSE-AGPL)
• Commercial — Contact for proprietary/commercial use (LICENSE-COMMERCIAL)

See LICENSE for details.