Part of the CronCommander project — a control plane for cron jobs across your infrastructure.
CronCommander Agent is a lightweight Go binary that connects your servers to the CronCommander control plane. It gives you visibility and control over cron jobs without replacing cron itself.
- Daemon Mode: Long-lived agent using short HTTPS requests to
gateway.croncommander.com - Cron Synchronization: Receives the deterministic, plan-eligible job manifest from the server and writes it to
/etc/cron.d/croncommander. Plan enforcement stays in the control plane, so jobs suppressed after a downgrade are not deleted by the agent. - Cron Discovery: Scans existing user and system cron sources for review and import
- Execution Wrapper: Wraps each job to capture stdout/stderr, exit codes, and timing
- Bounded Durable Spool: Retains reports across outages with configurable age, record, and byte limits
- Dual Modes: User Mode (unprivileged, manages its own crontab) or System Mode (root, manages
/etc/cron.d) - Security Hardened: No-new-privileges, minimal environment, controlled working directory
- Version Injection: Version is embedded at compile time via
-ldflags
Current release: v2.3.0. Published binaries and adjacent SHA-256 checksums are available from the GitHub Releases page.
curl -sSL https://croncommander.com/install.sh | bashSet your API key and gateway URL via environment variables:
CC_API_KEY="your-api-key" \
curl -sSL https://croncommander.com/install.sh | bashThe automatic service installer supports Linux and detects systemd, OpenRC, or
SysV init. FreeBSD and macOS release binaries require manual service
configuration.
Remote installs also download the adjacent .sha256 asset and refuse to
install a binary that does not match it.
-
Download the binary from the published GitHub Release or build from source:
make build
-
Verify the binary:
sha256sum -c cc-agent-2-3-0-linux-amd64.sha256
-
Install the binary:
sudo cp cc-agent-2-3-0-linux-amd64 /usr/local/bin/cc-agent sudo chmod 755 /usr/local/bin/cc-agent
-
Create config:
sudo mkdir -p /etc/croncommander sudo tee /etc/croncommander/config.yaml > /dev/null <<EOF api_key: your-api-key server_url: https://gateway.croncommander.com state_file: /var/lib/croncommander/agent-state.json spool_dir: /var/lib/croncommander/spool EOF
-
Run:
cc-agent daemon --config /etc/croncommander/config.yaml
The agent runs as a daemon, polling the CronCommander gateway with a randomized 30-90 second interval:
cc-agent daemon --config /etc/croncommander/config.yamlThe exec subcommand wraps job execution for reporting. It is called automatically by cron — not by users directly:
cc-agent exec --job-id abc123 -- /path/to/script.sh arg1 arg2This captures:
- Start time and duration
- Exit code
- stdout/stderr output (capped at 256KB each)
- Executing user and UID
The daemon scans after registration and then on the configured discovery interval (24 hours by default). Run an on-demand scan with:
cc-agent discover --config /etc/croncommander/config.yamlUser mode scans the agent user's crontab. System mode also scans
/etc/crontab and /etc/cron.d, excluding CronCommander-managed entries.
cc-agent --versionCronCommander Agent is designed with security as a first-class concern:
| Feature | Description |
|---|---|
| User Mode (default) | Agent runs as cc-agent-user, manages its own crontab only |
| System Mode | Opt-in root mode for /etc/cron.d management |
| No-new-privileges | Uses PR_SET_NO_NEW_PRIVS to prevent setuid escalation (Linux 3.5+) |
| Minimal environment | Only PATH, HOME, LANG, and LC_ALL are set |
| Controlled working directory | Jobs execute in /var/lib/croncommander |
| Systemd hardening | ProtectSystem=strict, ProtectHome=yes, NoNewPrivileges=yes |
For more details, see Security Documentation.
The agent is configured via YAML file:
# Workspace API key for authentication
api_key: your-workspace-api-key
# HTTPS gateway origin
server_url: https://gateway.croncommander.com
# Agent-scoped credential, manifest state, and durable report queue
state_file: /var/lib/croncommander/agent-state.json
spool_dir: /var/lib/croncommander/spool
# Durable report queue bounds (oldest reports are evicted first)
spool_max_bytes: 268435456
spool_max_records: 10000
spool_retention: 720h
# Local development only; leave false in production
allow_insecure_http: false
# Execution mode: "user" (default) or "system"
execution_mode: user
# Full host cron scan interval (minimum 5m)
discovery_interval: 24hDefault config location: /etc/croncommander/config.yaml
- Go 1.25+
- The repository
VERSIONfile (read automatically by the Makefile)
Before every agent build, review the changes since the previous build and
increase the repository VERSION value using semantic versioning:
- Patch for backward-compatible fixes
- Minor for backward-compatible features
- Major for breaking changes
Do not distribute or deploy a changed agent binary under a previously used version. The build embeds this value in the binary and reports it to CronCommander during registration and polling.
make buildProduces versioned binaries and adjacent checksum files in bin/, e.g.
cc-agent-2-3-0-linux-amd64 and
cc-agent-2-3-0-linux-amd64.sha256.
For the local Docker Compose agents, build and sync the Linux amd64 artifact:
make local-linux-amd64make publishCopies binaries and checksums to releases/ and ../build/ for local
development.
go test ./...Ownership, workspace roles, and Agency approvals are enforced in cc-server.
Pending or rejected proposals never change the effective job manifest. After
independent approval, the listener returns the committed definition through the
existing HTTPS v2 poll protocol. Approved disable/delete operations remove the
job on the next successful poll; previously installed cron remains in effect
while a proposal is pending or the gateway is unreachable. No agent upgrade or
new protocol is required for this governance rollout.
┌─────────────────────────────────────────────────────────┐
│ Host/Container │
│ │
│ ┌──────────────┐ ┌─────────────────────────────┐ │
│ │ cc-agent │◄───│ /etc/cron.d/croncommander │ │
│ │ (daemon) │ └─────────────────────────────┘ │
│ │ │ │
│ │ HTTPS poller │ ┌─────────────────────────────┐ │
│ │ and spool │◄───│ cc-agent exec │ │
│ │ │ │ (reports via Unix socket) │ │
│ └──────┬───────┘ └─────────────────────────────┘ │
│ │ │
└─────────┼───────────────────────────────────────────────┘
│
▼
┌─────────────────────┐
│ CronCommander │
│ Gateway │
│ (gateway. │
│ croncommander.com) │
└─────────────────────┘
Apache-2.0 — see LICENSE
Part of the CronCommander project — a control plane for cron jobs across your infrastructure.
- Website: https://croncommander.com
- Documentation: https://croncommander.com/docs.html
- Pricing: https://croncommander.com/pricing.html
- GitHub: https://github.com/croncommander