# Installing Agcron

> Install, configure, and verify the agent-cron daemon.

- Skill: `spillwavesolutions/installing-agcron` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add spillwavesolutions/installing-agcron`
- Raw SKILL.md: https://api.skillmd.com/api/skills/spillwavesolutions/installing-agcron/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: spillwavesolutions (https://skillmd.com/u/spillwavesolutions)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/spillwavesolutions/installing-agcron

---


# 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)

```bash
brew tap SpillwaveSolutions/agcron
brew install agcron
```

Homebrew installs to a standard PATH location automatically.

### Option 2: Shell Installer (macOS and Linux)

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

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

On macOS, if Gatekeeper prevents the binary from opening:

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

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

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

```toml
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:

```toml
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:

```bash
agcron --version
```

Check the daemon status:

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

```bash
agcron daemon
```

To run in the background (daemonize):

```bash
agcron daemon -d
```

Or run via cargo during development:

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

```bash
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](https://rustup.rs/)).