Metadata-Version: 2.4
Name: clevagent-runner
Version: 0.1.0
Summary: Local agent runner for ClevAgent — heartbeat proxy and remote restart executor.
License-Expression: MIT
Project-URL: Homepage, https://clevagent.io
Project-URL: Documentation, https://clevagent.io/docs
Keywords: ai,agent,monitoring,heartbeat,runner,restart
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# clevagent-runner

Local agent runner for [ClevAgent](https://clevagent.io) — 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

```bash
pip install clevagent-runner
```

Requires Python 3.8+. No system dependencies beyond `requests`.

## Quick Start

```bash
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)

```xml
<!-- ~/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>
```

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

### Linux (systemd)

```ini
# /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
```

```bash
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](LICENSE).
