clevagent-runner 0.1.0

Local agent runner for ClevAgent — heartbeat proxy and remote restart executor.

clevagent-runner

Local agent runner for ClevAgent — heartbeat proxy and remote restart executor.

Document role:

• package-level operator guide for clevagent-runner
• focuses on runner installation, flags, and local execution behavior
• broader product/tier contracts belong in the repo root docs and public site docs

What It Does

clevagent-runner runs alongside your AI agents on your machine or server. It:

1. Heartbeat proxy — Checks whether each watched process/container is alive and sends heartbeats to ClevAgent on its behalf. No changes needed inside your agent code.
2. Command executor — Polls ClevAgent for restart/stop commands and executes them securely. Only targets explicitly listed in --watch can be restarted (whitelist enforced at runtime).

Installation

pip install clevagent-runner

Requires Python 3.8+. No system dependencies beyond requests.

Quick Start

clevagent-runner start \
  --api-key "cv_your_project_key" \
  --watch "docker:my-trading-bot" \
  --watch "launchd:com.mycompany.crypto-agent"

Your project API key is available in the ClevAgent dashboard under Settings → API Key.

Supported Watch Types

Type	Target format	Example
docker	Container name	docker:my-bot
systemd	Service name	systemd:my-agent.service
launchd	Label (macOS)	launchd:com.myco.agent
process	pgrep -f substring	process:python agent.py

Options

clevagent-runner start --help

  --api-key TEXT            ClevAgent project API key (cv_xxx)  [required]
  --watch TYPE:TARGET       Process to watch. Repeatable.
  --endpoint URL            ClevAgent server (default: https://clevagent.io)
  --heartbeat-interval INT  Seconds between heartbeats (default: 30)
  --log-level LEVEL         DEBUG|INFO|WARNING|ERROR (default: INFO)

Running as a Background Service

macOS (launchd)

<!-- ~/Library/LaunchAgents/io.clevagent.runner.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>io.clevagent.runner</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/clevagent-runner</string>
    <string>start</string>
    <string>--api-key</string><string>cv_YOUR_KEY</string>
    <string>--watch</string><string>docker:my-agent</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardErrorPath</key><string>/tmp/clevagent-runner.err.log</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/io.clevagent.runner.plist

Linux (systemd)

# /etc/systemd/system/clevagent-runner.service
[Unit]
Description=ClevAgent Runner
After=network.target

[Service]
ExecStart=/usr/local/bin/clevagent-runner start \
  --api-key cv_YOUR_KEY \
  --watch docker:my-agent
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

systemctl enable --now clevagent-runner

Security

• Whitelist-only: Only targets passed via --watch can receive restart/stop commands from the server.
• No shell execution: Commands are assembled from hardcoded safe templates with shell=False.
• API key scoped: The runner only has access to agents in your project.

License

MIT — see LICENSE.