Scheduling

Background jobs, cron scheduling, and task management for automated workflows and maintenance.

On this page

SystemPrompt includes a built-in job scheduler for running background tasks, maintenance operations, and automated workflows. Jobs run on cron schedules with full logging and history.

Overview

The scheduling system provides:

  • Cron-style scheduling - Standard cron syntax for job timing
  • Manual execution - Run jobs on-demand via CLI
  • Job history - Track execution status and results
  • Enable/disable - Control job activation without deletion
  • Built-in maintenance - Session and log cleanup jobs included

CLI Commands

List Jobs

systemprompt infra jobs list

Shows each job's name, cron schedule, enabled status, and last run time.

Show Job Details

systemprompt infra jobs show cleanup-sessions
systemprompt infra jobs show log-cleanup

Returns:

  • Job name and description
  • Cron schedule
  • Enabled status
  • Last run time and result
  • Next scheduled run

Run Job Manually

systemprompt infra jobs run cleanup-sessions
systemprompt infra jobs run log-cleanup

Executes the job immediately, regardless of schedule.

View Job History

# View recent job runs
systemprompt infra jobs history

# Limit results
systemprompt infra jobs history --limit 20

# Filter by job
systemprompt infra jobs history --job cleanup-sessions

Enable/Disable Jobs

# Enable a job
systemprompt infra jobs enable cleanup-sessions

# Disable a job
systemprompt infra jobs disable cleanup-sessions

Disabled jobs remain in the system but won't run on schedule.

Built-in Jobs

SystemPrompt includes maintenance jobs out of the box:

Session Cleanup

Removes expired sessions:

# Run with default retention (24 hours)
systemprompt infra jobs cleanup-sessions

# Custom retention period
systemprompt infra jobs cleanup-sessions --hours 48

Log Cleanup

Removes old log entries:

# Run with default retention (30 days)
systemprompt infra jobs log-cleanup

# Custom retention period
systemprompt infra jobs log-cleanup --days 90

Job Configuration

Jobs are defined in services/scheduler/config.yaml:

jobs:
  cleanup-sessions:
    schedule: "0 2 * * *"  # Daily at 2 AM
    enabled: true
    retention_hours: 24

  log-cleanup:
    schedule: "0 3 * * 0"  # Weekly on Sunday at 3 AM
    enabled: true
    retention_days: 30

Cron Syntax

Standard five-field cron format:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Common patterns:

  • 0 * * * * - Every hour
  • 0 0 * * * - Daily at midnight
  • 0 2 * * * - Daily at 2 AM
  • 0 0 * * 0 - Weekly on Sunday
  • 0 0 1 * * - Monthly on the 1st

Custom Jobs

Create custom jobs by implementing the job interface in an extension:

// extensions/my-extension/src/jobs.rs
use systemprompt::jobs::{Job, JobContext, JobResult};

pub struct MyCustomJob;

impl Job for MyCustomJob {
    fn name(&self) -> &str {
        "my-custom-job"
    }

    async fn run(&self, ctx: &JobContext) -> JobResult {
        // Job logic here
        Ok(())
    }
}

Register in extension configuration:

# services/scheduler/config.yaml
jobs:
  my-custom-job:
    schedule: "0 4 * * *"
    enabled: true

Monitoring Jobs

Check Job Status

# View all jobs
systemprompt infra jobs list

# Check specific job
systemprompt infra jobs show cleanup-sessions

View Logs

# Recent job-related logs
systemprompt infra logs view --level info --since 1h

# Search for errors
systemprompt infra logs search "job failed"

Troubleshooting

Issue Cause Solution
Job not running Disabled infra jobs enable <name>
Job not running Schedule wrong Check cron in infra jobs show <name>
Job failing Runtime error Check infra logs search "job"
Missed runs Service down Jobs catch up when service restarts

Debug Failed Jobs

# Check job history
systemprompt infra jobs history --job <name>

# View error logs
systemprompt infra logs view --level error --since 1h

# Manual run for testing
systemprompt infra jobs run <name>

Next Steps

-> See Feature: The Closed Loop

Playbooks:

  • systemprompt core playbooks show cli_jobs - Job management
Previous Next
File Storage Complete Workflow