cc-agent

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.

Features

• Daemon Mode: Long-lived agent connecting via WebSocket to gateway.croncommander.com
• Cron Synchronization: Receives job definitions from the server and writes them to /etc/cron.d/croncommander
• Execution Wrapper: Wraps each job to capture stdout/stderr, exit codes, and timing
• 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

Installation

Quick Install (Linux / FreeBSD / macOS)

curl -sSL https://croncommander.com/install.sh | bash

Set your API key and gateway URL via environment variables:

CC_API_KEY="your-api-key" \
  curl -sSL https://croncommander.com/install.sh | bash

The installer auto-detects your OS and architecture and downloads the correct binary.

Manual Installation

1. Download the binary from releases/ or build from source:

   make build

2. Install the binary:

   sudo cp bin/cc-agent-*-linux-amd64 /usr/local/bin/cc-agent
   sudo chmod 755 /usr/local/bin/cc-agent

3. Create config:

   sudo mkdir -p /etc/croncommander
   sudo tee /etc/croncommander/config.yaml > /dev/null <<EOF
   api_key: your-api-key
   server_url: wss://gateway.croncommander.com/
   EOF

4. Run:

   cc-agent daemon --config /etc/croncommander/config.yaml

Usage

Daemon Mode

The agent runs as a daemon, maintaining a WebSocket connection to the CronCommander gateway:

cc-agent daemon --config /etc/croncommander/config.yaml

Exec Mode

The 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 arg2

This captures:

• Start time and duration
• Exit code
• stdout/stderr output (capped at 256KB each)
• Executing user and UID

Version

cc-agent --version

Security

CronCommander 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.

Configuration

The agent is configured via YAML file:

# Agent version
version: 1.1.0

# Workspace API key for authentication
api_key: your-workspace-api-key

# WebSocket gateway URL
server_url: wss://gateway.croncommander.com/

# Execution mode: "user" (default) or "system"
execution_mode: user

Default config location: /etc/croncommander/config.yaml

Building

Requirements

• Go 1.23+
• The root VERSION file (read automatically by the Makefile)

Build

make build

Produces versioned binaries in bin/, e.g. cc-agent-1-1-0-linux-amd64.

Publish Release

make publish

Copies binaries to releases/ and ../build/ for local development.

Testing

go test ./...

Architecture

┌─────────────────────────────────────────────────────────┐
│  Host/Container                                         │
│                                                         │
│  ┌──────────────┐    ┌─────────────────────────────┐   │
│  │  cc-agent    │◄───│  /etc/cron.d/croncommander  │   │
│  │  (daemon)    │    └─────────────────────────────┘   │
│  │              │                                       │
│  │  WebSocket   │    ┌─────────────────────────────┐   │
│  │  connection  │◄───│  cc-agent exec              │   │
│  │              │    │  (reports via Unix socket)  │   │
│  └──────┬───────┘    └─────────────────────────────┘   │
│         │                                               │
└─────────┼───────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────┐
│  CronCommander      │
│  Gateway             │
│  (gateway.           │
│   croncommander.com) │
└─────────────────────┘

License

Apache-2.0 — see LICENSE

Project

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