runsentry-agent 1.0.0

RunSentry Agent - Monitor and track scheduled job executions

RunSentry Agent

The RunSentry agent monitors and tracks scheduled job executions on Linux systems. It discovers cron jobs and Kubernetes CronJobs, tracks their executions, and sends data to the RunSentry backend.

Features

• 🔍 Automatic Discovery: Discovers cron jobs and Kubernetes CronJobs
• 📊 Execution Tracking: Tracks job start, finish, duration, and exit codes
• 🔒 Secure: Outbound-only HTTPS communication, no inbound ports
• 💾 Resilient: Local event buffering for offline operation
• 🚀 Easy Installation: One-line installer script

Quick Start

Installation

One-line installation with automatic registration:

RUNSENTRY_TOKEN=your_token_here curl -fsSL https://get.runsentry.io/install.sh | bash

The installer will:

1. Validate Linux OS and Python 3.10+
2. Create isolated virtual environment at /opt/runsentry/venv
3. Install the RunSentry agent package
4. Automatically register agent with backend (if RUNSENTRY_TOKEN is provided)
5. Install and enable systemd service
6. Start the service automatically if registration succeeds

Installation without token (for later registration):

curl -fsSL https://get.runsentry.io/install.sh | bash

# Register manually later
RUNSENTRY_TOKEN=xxx /opt/runsentry/venv/bin/runsentry register --backend-url https://api.runsentry.io
systemctl start runsentry-agent

With custom backend URL:

RUNSENTRY_TOKEN=xxx RUNSENTRY_BACKEND_URL=https://api.example.com curl -fsSL https://get.runsentry.io/install.sh | bash

Usage

Daemon Mode

The agent runs as a systemd service automatically after installation:

# Check status
systemctl status runsentry-agent

# View logs
journalctl -u runsentry-agent -f

# Restart
systemctl restart runsentry-agent

The daemon will:

• Discover jobs on startup and periodically (every hour)
• Flush buffered events to the backend (every minute)
• Run continuously until stopped

Execution Wrapper

Wrap your cron jobs to track executions:

# Instead of:
0 * * * * /path/to/script.sh

# Use:
0 * * * * /opt/runsentry/venv/bin/runsentry exec /path/to/script.sh

The wrapper will:

• Send execution start event
• Execute your command
• Capture exit code and duration
• Send execution finish event
• Works even if backend is temporarily unavailable (events are buffered)

CLI Commands

The agent exposes three commands:

• runsentry daemon - Run agent daemon (used by systemd service)
• runsentry exec <command> - Execute and track a job execution
• runsentry register - Register agent with backend (internal, used by install.sh)

Note: The register command is internal and used automatically by install.sh. Manual registration can be done if needed:

/opt/runsentry/venv/bin/runsentry register --token xxx --backend-url https://api.runsentry.io

Configuration

Configuration is stored at /etc/runsentry/config.yaml:

agent_id: agt_123
backend_url: https://api.runsentry.io
token: <signed-jwt>
agent_name: prod-vm-1

Discovery

The agent automatically discovers:

• Linux Cron:

  • User crontab (crontab -l)
  • System crontab (/etc/crontab)
  • Cron.d directory (/etc/cron.d/*)

• Kubernetes CronJobs:

  • Requires kubernetes Python package
  • Uses in-cluster config or kubeconfig
  • Discovers all namespaces

Systemd Service

The agent runs as a systemd service:

# Check status
systemctl status runsentry-agent

# View logs
journalctl -u runsentry-agent -f

# Restart
systemctl restart runsentry-agent

# Stop
systemctl stop runsentry-agent

Upgrading

Upgrade the agent package manually:

source /opt/runsentry/venv/bin/activate
pip install --upgrade runsentry-agent
systemctl restart runsentry-agent

Configuration is preserved during upgrades.

Development

Local Development Setup

# Clone repository
git clone https://github.com/runsentry/agent.git
cd agent

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

# Install with Kubernetes support
pip install -e ".[k8s]"

Running Tests

pytest

Architecture

The agent operates in two modes:

1. Daemon Mode: Continuous background process for discovery and sync
2. Exec Mode: Wrapper for individual job executions

All communication is outbound-only HTTPS to the RunSentry backend.

Security

• ✅ Outbound-only HTTPS
• ✅ Token-based authentication
• ✅ Signed agent JWT
• ✅ Read-only discovery permissions
• ✅ No inbound ports
• ✅ Secure configuration file (600 permissions)

Requirements

• Python 3.10+
• Linux (Ubuntu, Debian, RHEL, etc.)
• Network access to RunSentry backend
• Root or sudo access for installation

Troubleshooting

Agent not discovering jobs

• Check that cron jobs exist: crontab -l
• Verify agent has read permissions to /etc/crontab and /etc/cron.d/
• Check daemon logs: journalctl -u runsentry-agent

Events not reaching backend

• Check network connectivity to backend URL
• Verify agent token is valid
• Check buffered events: /var/lib/runsentry/buffer/events.jsonl
• Review logs for errors

Service won't start

• Check Python version: python3 --version
• Verify virtual environment exists: /opt/runsentry/venv
• Check systemd logs: journalctl -u runsentry-agent

License

MIT License

Support

For issues and questions:

• Documentation: https://docs.runsentry.io
• Support: [e-mail]