installing-agcron

name	installing-agcron
description	Install, configure, and verify the agent-cron daemon.
last_validated	"2026-03-21T00:00:00.000Z"

Installing Agent Cron

This skill covers installing agent-cron, configuring it, and verifying the installation. Pre-built binaries are available for macOS and Linux — no Rust toolchain required.

Quick Install

Option 1: Homebrew (macOS, recommended)

brew tap SpillwaveSolutions/agcron
brew install agcron

Homebrew installs to a standard PATH location automatically.

Option 2: Shell Installer (macOS and Linux)

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/SpillwaveSolutions/agent-cron/releases/latest/download/agent-cron-installer.sh | sh

The installer places agcron at ~/.cargo/bin/agcron. If the binary is not found after install:

export PATH="$HOME/.cargo/bin:$PATH"
# Add this line to ~/.bashrc or ~/.zshrc for persistence

On macOS, if Gatekeeper prevents the binary from opening:

xattr -cr $(which agcron)

Configuration

The daemon reads its configuration from a TOML file.

Config file location

By default, the config file is at:

~/.config/agent-cron/config.toml

Override the config file path with the AGENT_CRON_CONFIG environment variable:

export AGENT_CRON_CONFIG=/path/to/custom/config.toml

Scaffolding a project

Run agcron init in any project directory to create the required directory structure:

cd /path/to/your/project
agcron init

This creates:

• .cron/jobs/ directory for job definitions
• Updates ~/.config/agent-cron/config.toml to register the project directory in project_roots (creates the config file with defaults if it does not exist)

Config file structure

The config file uses TOML format. All fields have sensible defaults. A minimal config only needs project_roots:

project_roots = ["/path/to/project1", "/path/to/project2"]

Key configuration fields:

• project_roots -- Directories to watch for cron job files
• concurrency_limit -- Maximum concurrent job executions (default: 4)
• default_agent -- Default AI CLI adapter, e.g. claude, opencode (default: "claude")
• default_model -- Default model when not specified in a job (default: "claude-3-5-sonnet")
• default_timeout_secs -- Execution timeout per job in seconds (default: 300)
• socket_path -- Unix socket path for IPC (default: ~/.config/agent-cron/agent-cron.sock)
• log_retention_days -- Days to keep execution logs (default: 30)
• max_retries -- Retry attempts for failed jobs (default: 2)
• retry_delay_secs -- Delay between retries in seconds (default: 5)
• shutdown_timeout_secs -- Grace period for in-flight jobs during shutdown (default: 30)

See skills/agcron/installing-agcron/references/config-reference.md for the complete field reference.

Environment variable expansion

Config values support ${VAR} syntax for environment variable expansion:

project_roots = ["${HOME}/projects/my-app"]
socket_path = "${XDG_RUNTIME_DIR}/agcron.sock"

Missing variables expand to an empty string.

Environment variable overrides

Two environment variables override config file values directly:

• AGENT_CRON_CONFIG -- Path to the config file (overrides the default location)
• AGENT_CRON_SOCKET -- Unix socket path (overrides socket_path in config)

Verifying the Installation

Check that the binary is installed and accessible:

agcron --version

Check the daemon status:

agcron status

This connects to the daemon's Unix socket and reports whether it is running, how many jobs are loaded, and current concurrency usage.

Running the Daemon

Start the daemon (foreground):

agcron daemon

To run in the background (daemonize):

agcron daemon -d

Or run via cargo during development:

cargo run --manifest-path rust/Cargo.toml -- daemon

The daemon will:

1. Load configuration from ~/.config/agent-cron/config.toml (or create a default)
2. Watch each directory listed in project_roots for .cron/jobs/*.md files
3. Parse and schedule jobs based on their cron expressions
4. Execute jobs using the configured AI CLI adapters

Running Tests

cargo test --manifest-path rust/Cargo.toml

Troubleshooting

• Binary not found: Ensure the install location is on your PATH
• Config parse error: Run with RUST_LOG=debug to see detailed config loading output
• Socket already in use: A previous daemon instance may still be running; check with agcron status or remove the stale socket file
• Permission denied on socket: Check file permissions on the socket path directory

Building from Source (Fallback)

If no pre-built binary exists for your platform, or you need a development build, see:

skills/agcron/installing-agcron/references/build-from-source.md

Requires Rust 1.75+ and cargo (install via rustup).