中文 | Deutsch | English | Español | français | 日本語 | 한국어 | Português | Русский

A cross-platform lightweight task scheduler with advanced features.

🌟 Recommended: OllaMan - Powerful Ollama AI Model Manager.

Cronx is a cross-platform, lightweight task scheduler designed to simplify the management of scheduled tasks. It allows you to define and execute tasks with ease using simple configuration files. Whether you're automating scripts or setting up regular maintenance tasks, Cronx provides a flexible and efficient solution with features like retry mechanisms, timeout control, concurrency management, and task monitoring.

You can install Cronx using one of the following methods:

Ensure you have Golang installed, then run the following command:

go install github.com/jae-jae/cronx@latest

Alternatively, you can download the pre-built binary from the releases page on GitHub. Choose the appropriate version for your operating system, download the binary, and add it to your system's PATH.

You can run Cronx using Docker with the official image from GitHub Container Registry:

# Pull the latest image
docker pull ghcr.io/jae-jae/cronx:latest

# Run with a configuration file
docker run -v $(pwd)/cronx.yaml:/app/cronx.yaml ghcr.io/jae-jae/cronx:latest

For easier deployment, you can use Docker Compose. Create a docker-compose.yml file:

version: "3.8"

services:
  cronx:
    image: ghcr.io/jae-jae/cronx:latest
    container_name: cronx
    volumes:
      - ./cronx.yaml:/app/cronx.yaml:ro
      - ./logs:/app/logs
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai # Set your timezone

Then run:

docker-compose up -d

Run a cron task:

cronx

Specify the configuration file path:

cronx -c cronx.yaml

Run tasks once, typically for testing purposes:

cronx run task1 task2
# or
cronx -c cronx.yaml run task1 task2

List all configured tasks with their schedules:

cronx list

Check the status of running and queued tasks (requires cronx daemon to be running):

cronx status

Validate your configuration file:

cronx validate

Show version information:

cronx version

For production environments, you can use PM2 to run Cronx as a background service:

# Install PM2 globally
npm install -g pm2

# Start Cronx as a background service
pm2 start cronx -c cronx.yaml

# Monitor the service
pm2 logs cronx
pm2 status

# Stop the service
pm2 stop cronx

# Restart the service
pm2 restart cronx

# Save PM2 configuration to start on system boot
pm2 save
pm2 startup

The configuration file cronx.yaml is used to define tasks and their schedules. By default, Cronx looks for this file in the current directory.

Below is an example of a basic configuration:

# scheduled task list
tasks:
  task1:
    schedule: "@every 1s"
    commands:
      - echo "hello world1!"

Here is an example of a more complete configuration:

# Global Settings
settings:
  timezone: "UTC"
  log_path: "/var/log/cronx.log" # Optional: cronx log file path

# Set global environment variables
env:
  KEY1: value1
  KEY2: value2

# Scheduled task list
tasks:
  simple-task:
    schedule: "@every 1s"
    commands:
      - echo "Simple task executed at $(date)"

  task-with-retry:
    schedule: "@every 30s"
    dir: /tmp
    commands:
      - echo "Task with retry and timeout"
      - curl -f "http://example.com/api" # This might fail
    timeout: "10s" # Task timeout
    output: "/var/log/api-task.log" # Task output file
    concurrency: "skip" # Skip if already running
    on_failure:
      retries: 3 # Retry 3 times on failure
      retry_delay: "5s" # Wait 5s between retries
    env:
      API_KEY: "your-api-key"

  backup-task:
    schedule: "0 2 * * *" # Daily at 2 AM
    commands:
      - /usr/local/bin/backup.sh
      - echo "Backup completed"
    timeout: "1h" # 1 hour timeout
    output: "/var/log/backup.log"
    concurrency: "queue" # Queue if already running

  quick-task:
    schedule: "@every 10s"
    commands:
      - echo "Quick task"
      - ls -la

  long-running-task:
    schedule: "@every 1m"
    commands:
      - sleep 90 # This will take longer than schedule interval
    concurrency: "skip" # Skip if previous run is still active

The following table describes the fields used in the cronx.yaml configuration file:

• allow: Allow multiple instances of the same task to run concurrently (default)
• skip: Skip execution if the task is already running
• queue: Queue the new execution until the current one finishes

• Timeout Support: Set maximum execution time for tasks
• Retry Mechanism: Automatically retry failed tasks with configurable delays
• Output Redirection: Redirect task output to specific log files
• Concurrency Management: Control how concurrent executions are handled

cronx provides real-time status monitoring through an HTTP API server that starts automatically with the daemon.

Add the API port to your configuration file:

settings:
  api_port: 8665  # Default port, optional

1. Start the cronx daemon (this also starts the API server):

   cronx -c cronx.yaml

2. Check status from another terminal:

   cronx status -c cronx.yaml

The HTTP API provides the following endpoints:

• GET /status - Get detailed task status information
• GET /health - Health check endpoint

Example API usage:

# Get status as JSON
curl http://localhost:8665/status

# Health check
curl http://localhost:8665/health

The status command shows:

• Running Tasks: Currently executing tasks with instance IDs, start times, and durations
• Queued Tasks: Tasks waiting in queue with wait times (when using concurrency: "queue")
• Real-time Updates: Live data from the running cronx daemon

For detailed documentation, refer to the robfig/cron documentation .

A cron expression consists of six space-separated fields:

* * * * * *
| | | | | |
| | | | | +-- Seconds (0 - 59)
| | | | +---- Minutes (0 - 59)
| | | +------ Hours (0 - 23)
| | +-------- Day of the month (1 - 31)
| +---------- Month (1 - 12) (or JAN-DEC)
+------------ Day of the week (0 - 6) (or SUN-SAT)

You can use predefined schedules instead of a cron expression:

You can also schedule jobs to execute at fixed intervals:

@every <duration>

where "duration" is a string accepted by time.ParseDuration (http://golang.org/pkg/time/#ParseDuration).

For example, @every 1h30m10s schedules a job to run every 1 hour, 30 minutes, and 10 seconds.

Note: The interval does not account for the job runtime. If a job takes 3 minutes to run and is scheduled to run every 5 minutes, there will be 2 minutes of idle time between runs.

• Go 1.24 or later
• Make (optional)

# Build for current platform
make build

# Build for all platforms
make build-all

# Run tests
make test

# Run tests with coverage
make test-coverage

# Validate configuration
make validate

# Install to system
make install

• robfig/cron