cirun-agent

A robust Rust agent for provisioning and managing CI/CD runners through the Cirun platform, offering automated VM lifecycle management with Lume (macOS) and Meda (Linux) virtualization.

✨ Features

• Automatic VM Provisioning: Clone and configure runner VMs from templates
• Lifecycle Management: Provision and delete CI/CD runners on demand
• Template-based Deployment: Use a base template for consistent runner configurations
• Continuous Communication: Regular status reporting to the Cirun API
• Persistent Agent Identity: Maintains a consistent identifier across restarts
• Environment Detection: Auto-detects system information and capabilities

📦 Installation

Using binary (recommended)

curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/cirunlabs/cirun-agent/refs/heads/main/install.sh | sh

Using Cargo

cargo install cirun-agent

From Source

git clone https://github.com/cirunlabs/cirun-agent
cd cirun-agent
cargo build --release

🚀 Quick Start

Install as System Service

Install and run cirun-agent as a persistent system service (survives reboots):

# Linux (systemd)
export CIRUN_API_TOKEN=YOUR_TOKEN
sudo -E cirun-agent --install-service

# macOS (launchd)
export CIRUN_API_TOKEN=YOUR_TOKEN
cirun-agent --install-service

The service will:

• Start automatically on boot
• Restart on failure
• Log to system journal (Linux) or ~/Library/Logs/cirun-agent.log (macOS)

Run Manually

export CIRUN_API_TOKEN=YOUR_TOKEN
cirun-agent

For more details, checkout docs: https://docs.cirun.io/on-prem

⚙️ Configuration

Environment Variables

Variable	Description	Default
CIRUN_API_TOKEN	API token for authentication (preferred — keeps the secret out of argv / ps / shell traces). Required unless installing/uninstalling the service.	—
CIRUN_API_URL	Base URL for Cirun API	https://api.cirun.io/api/v1

Command Line Arguments

Argument	Short	Description	Default
--interval	-i	Polling interval in seconds	5
--id-file	-f	Agent ID file path	.agent_id
--verbose	-v	Enable verbose logging	false
--install-service		Install as system service	false
--max-runners		Maximum concurrent runners — VMs or containers (min: 1). Old alias: --max-vms.	2 (macOS), unlimited (Linux)
--executors		Comma-separated allow-list of executor backends to enable. Accepted values: docker, meda, lume. When unset, every executor available on the host is enabled. Use this to suppress the auto-install of meda (Linux) or lume (macOS) — for example --executors docker runs a docker-only agent.	all available

🔌 Virtualization

Cirun-agent uses platform-specific virtualization:

• Linux: Meda - Lightweight KVM-based VM management
• macOS: Lume - Virtualization framework for macOS

Note: The agent automatically downloads and manages the VM platform, so there's no need to install Lume or Meda separately.

💡 Usage Scenarios

Self-Hosted CI/CD Runners

Set up the agent on any machine with virtualization capabilities to automatically provision CI/CD runners when needed, and clean them up after use.

# Run with custom polling interval (30 seconds)
export CIRUN_API_TOKEN=YOUR_TOKEN
cirun-agent --interval 30

Custom Runner Templates

1. Create a VM named cirun-runner-template using Lume (macOS) or Meda (Linux)
2. Configure it with your required tools and settings
3. Start the agent - it will clone this template when provisioning new runners

Limiting Concurrent Runners

Control the maximum number of runners (VMs or containers) running simultaneously:

# Limit to 5 concurrent runners (useful for resource management)
export CIRUN_API_TOKEN=YOUR_TOKEN
cirun-agent --max-runners 5

# macOS automatically defaults to 2 runners (Apple Virtualization framework limit on lume VMs)
# Linux has no default limit unless specified

Note: On macOS, the Apple Virtualization framework caps concurrent VMs at 2 on most hardware, so the agent defaults to --max-runners 2 automatically. --max-vms is kept as a deprecated alias for backward compatibility.

🏗️ Architecture

The agent works by:

1. Registering itself with the Cirun API using a persistent UUID
2. Polling the API at regular intervals for runner provisioning/deletion requests
3. Using Lume (macOS) or Meda (Linux) to clone VMs from a template and run provisioning scripts
4. Reporting VM status back to the Cirun platform

👨‍💻 Development

Prerequisites

• Rust 1.54 or later
• Virtualization support (KVM for Linux, Virtualization.framework for macOS)
• Cirun API credentials

Building

cargo build

Testing

cargo test

Linting and Formatting

The project uses Clippy for linting and rustfmt for code formatting.

Install Linting Tools

rustup component add clippy rustfmt

Run Linter

cargo clippy

To automatically fix some linting issues:

cargo clippy --fix

Format Code

cargo fmt

Pre-commit Checks

Run both linting and formatting checks before committing:

cargo fmt -- --check && cargo clippy

🔍 Troubleshooting

Debug Logging

Enable detailed logs by setting the RUST_LOG environment variable:

export CIRUN_API_TOKEN=YOUR_TOKEN
RUST_LOG=debug cirun-agent

📚 Documentation

For comprehensive documentation about Cirun and the on-premises deployment options, visit:

• Cirun Documentation
• On-Premises Guide

💬 Support

• Slack: slack.cirun.io
• Email: amit@cirun.io

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🚢 Release Process

• Update the version in Cargo.toml
• Make sure all changes are staged for commit
• Run the release script: ./release.sh

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request