Background Automation

Overview

Mission Control’s scheduler runs automated maintenance tasks in the background without manual intervention. Handle database backups, stale data cleanup, agent heartbeat checks, webhook retries, and Claude Code session scanning.

The scheduler initializes automatically on startup and runs tasks based on configured intervals. No user action required.

Accessing Scheduler Status

Navigate to Settings

Click Settings in the left navigation rail.

Open Background Tasks

Scroll to the Background Tasks section.

View Task Status

See last run time, next scheduled run, and enabled/disabled status for each task.

Via API

Query scheduler status programmatically:

curl http://localhost:3000/api/scheduler \
  -H "x-api-key: your-api-key"

Response:

[
  {
    "id": "auto_backup",
    "name": "Auto Backup",
    "enabled": true,
    "lastRun": 1735696800000,
    "nextRun": 1735783200000,
    "running": false,
    "lastResult": {
      "ok": true,
      "message": "Backup created (2456KB)",
      "timestamp": 1735696800000
    }
  }
]

Scheduled Tasks

Five background tasks run automatically:

1. Auto Backup

Purpose: Create database backups to prevent data loss. Schedule: Daily at ~3 AM UTC (relative to process start time) What It Does:

Create Backup

Copies SQLite database to .data/backups/mc-backup-{timestamp}.db

Log Event

Records backup creation in audit log with file size

Prune Old Backups

Deletes backups older than retention count (default: keep 10)

Configuration:

{
  "general.auto_backup": true,
  "general.backup_retention_count": 10
}

Manual Trigger:

curl -X POST http://localhost:3000/api/scheduler \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"action": "trigger", "taskId": "auto_backup"}'

or use the dedicated backup endpoint:

curl -X POST http://localhost:3000/api/backup \
  -H "x-api-key: your-api-key"

Backup File Format

Filenames follow the pattern: mc-backup-YYYY-MM-DD_HH-MM-SS.dbExample: mc-backup-2026-03-04_03-00-00.db

2. Auto Cleanup

Purpose: Remove stale records based on retention policies. Schedule: Daily at ~4 AM UTC What It Does:

Delete Old Activities

Remove activity feed entries older than configured days

Delete Old Audit Logs

Remove audit trail entries older than configured days

Delete Old Notifications

Remove notifications older than configured days

Delete Old Pipeline Runs

Remove pipeline execution history older than configured days

Clean Token Usage File

Remove token records from tokens.json older than configured days

Log Summary

Record total number of deleted records in audit log

Configuration:

{
  "general.auto_cleanup": true,
  "retention.activities": 90,
  "retention.auditLog": 180,
  "retention.notifications": 30,
  "retention.pipelineRuns": 60,
  "retention.tokenUsage": 90
}

Set retention to 0 to disable cleanup for a specific record type. Records will be kept indefinitely.

Manual Trigger:

curl -X POST http://localhost:3000/api/cleanup \
  -H "x-api-key: your-api-key"

3. Agent Heartbeat Check

Purpose: Mark agents offline if they haven’t sent a heartbeat recently. Schedule: Every 5 minutes What It Does:

Query Stale Agents

Find agents with status != 'offline' and last_seen < threshold

Mark Offline

Update agent status to offline and set updated_at timestamp

Log Activity

Create activity feed entry: “Agent marked offline (no heartbeat for Xm)”

Create Notification

Notify operator: “Agent offline: ”

Audit Log

Record which agents were marked offline

Configuration:

{
  "general.agent_heartbeat": true,
  "general.agent_timeout_minutes": 10
}

If agents are frequently marked offline, increase agent_timeout_minutes or ensure agents are sending heartbeats regularly.

Manual Trigger:

curl -X POST http://localhost:3000/api/scheduler \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"action": "trigger", "taskId": "agent_heartbeat"}'

4. Webhook Retry

Purpose: Retry failed webhook deliveries with exponential backoff. Schedule: Every 60 seconds What It Does:

Query Failed Deliveries

Find webhook deliveries with status = 'failed' and next_retry <= now

Check Circuit Breaker

Skip webhooks that have exceeded max retries (circuit open)

Retry Delivery

Send HTTP request to webhook URL with payload

Update Status

Mark as success or increment retry count

Calculate Backoff

Set next_retry using exponential backoff (1s, 2s, 4s, 8s, 16s, …)

Configuration:

{
  "webhooks.retry_enabled": true,
  "webhooks.max_retries": 5,
  "webhooks.retry_backoff": 2.0
}

Manual Trigger:

curl -X POST http://localhost:3000/api/webhooks/retry/{deliveryId} \
  -H "x-api-key: your-api-key"

Circuit Breaker Behavior

After 5 consecutive failures, the webhook enters “circuit open” state:

No further retry attempts
Delivery status set to circuit_open
Operator notification created
Manual intervention required to reset

5. Claude Session Scan

Purpose: Auto-discover and track local Claude Code sessions. Schedule: Every 60 seconds What It Does:

Scan Projects Directory

Read ~/.claude/projects/ for active projects

Parse JSONL Transcripts

Extract conversation history from transcript files

Extract Token Usage

Parse API responses for token counts (input, output, total)

Calculate Cost

Multiply tokens by Claude model pricing

Store in Database

Upsert session records with source = 'claude-code'

Configuration:

{
  "general.claude_session_scan": true
}

Environment:

MC_CLAUDE_HOME=~/.claude

Manual Trigger:

curl -X POST http://localhost:3000/api/claude/sessions \
  -H "x-api-key: your-api-key"

Claude Code must be installed and have at least one project for scanning to work. Sessions are marked active if updated within the last hour.

Task Configuration

Enable/disable tasks via Settings API:

Enable a Task

curl -X PUT http://localhost:3000/api/settings \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "general.auto_backup": true
  }'

Disable a Task

curl -X PUT http://localhost:3000/api/settings \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "general.auto_cleanup": false
  }'

View All Settings

curl http://localhost:3000/api/settings \
  -H "x-api-key: your-api-key"

Retention Policies

Configure how long records are kept:

Activities
Audit Log
Notifications
Pipeline Runs
Token Usage

Key: retention.activitiesDefault: 90 daysActivity feed entries (task updates, agent changes, etc.)

Key: retention.auditLogDefault: 180 daysAudit trail entries (logins, config changes, etc.)

Key: retention.notificationsDefault: 30 daysSystem and agent notifications

Key: retention.pipelineRunsDefault: 60 daysPipeline execution history and logs

Key: retention.tokenUsageDefault: 90 daysToken consumption records in tokens.json

Set Retention Policy

curl -X PUT http://localhost:3000/api/settings \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "retention.activities": 60,
    "retention.auditLog": 365,
    "retention.notifications": 14
  }'

Retention policies apply during the next cleanup run. Previously deleted data cannot be recovered.

Scheduler Initialization

The scheduler starts automatically when Mission Control launches:

Agent Sync — Sync agents from openclaw.json on startup
Task Registration — Register all 5 background tasks
Staggered Start — Backup scheduled for ~3 AM, cleanup for ~4 AM (relative to start time)
Tick Loop — Check every 60 seconds for due tasks

Startup Log

Scheduler initialized - backup at ~3AM, cleanup at ~4AM, 
heartbeat every 5m, webhook retry every 60s, claude scan every 60s

Monitoring Task Execution

Last Run Information

Each task tracks:

lastRun — Timestamp of most recent execution
nextRun — Timestamp of next scheduled execution
running — Boolean indicating if task is currently executing
lastResult — Result of most recent execution:
- ok — Success/failure boolean
- message — Human-readable summary
- timestamp — When result was recorded

Example Result Messages

Auto Backup: "Backup created (2456KB)"
Auto Cleanup: "Cleaned 147 stale records"
Heartbeat Check: "All agents healthy" or "Marked 2 agent(s) offline: researcher-01, analyst-02"
Webhook Retry: "Retried 3 deliveries: 2 succeeded, 1 failed"
Claude Scan: "Synced 2 sessions: mission-control, demo-project"

Audit Trail

All scheduled task executions are logged to the audit trail:

curl http://localhost:3000/api/audit?action=auto_backup \
  -H "x-api-key: your-api-key"

Response:

[
  {
    "id": 123,
    "action": "auto_backup",
    "actor": "scheduler",
    "detail": {
      "path": ".data/backups/mc-backup-2026-03-04_03-00-00.db",
      "size": 2514944
    },
    "created_at": 1735696800
  }
]

Troubleshooting

Task Not Running

Check if task is enabled in settings
Verify nextRun timestamp is in the past
Confirm scheduler initialized (check startup logs)
Look for errors in lastResult.message

Backup Failing

Verify .data/backups/ directory exists and is writable
Check disk space: df -h .data/
Review permissions: ls -la .data/backups/
Check audit log for detailed error message

Cleanup Not Deleting Records

Confirm retention policies are set (not 0)
Verify records are older than retention days
Check if task is enabled: general.auto_cleanup = true
Manually trigger cleanup and review result

Agents Marked Offline Too Quickly

Increase timeout:

curl -X PUT http://localhost:3000/api/settings \
  -H "Content-Type: application/json" \
  -d '{"general.agent_timeout_minutes": 20}'

Best Practices

Backup Strategy

Enable Auto Backup

Always keep general.auto_backup = true in production.

Set Retention Count

Keep 10-30 backups depending on disk space and change frequency.

External Backup

Copy .data/backups/ to offsite storage weekly (e.g., S3, Google Drive).

Test Restoration

Periodically verify backups can be restored by copying to a test environment.

Retention Tuning

High-traffic systems — Reduce retention to 30-60 days to save disk space
Audit compliance — Increase audit log retention to 365+ days
Development — Use shorter retention (7-14 days) to keep database small

Heartbeat Tuning

Reliable networks — 10-minute timeout is fine
Unreliable networks — Increase to 20-30 minutes to avoid false positives
Local development — Consider disabling heartbeat checks entirely

Next Steps

Agent Management

Configure agent heartbeat intervals and SOUL files

Real-Time Monitoring

Monitor task execution in the activity feed

Get Started

Core Features

Integrations

Deployment

Advanced

Overview

Accessing Scheduler Status

Via API

Scheduled Tasks

1. Auto Backup

2. Auto Cleanup

3. Agent Heartbeat Check

4. Webhook Retry

5. Claude Session Scan

Task Configuration

Enable a Task

Disable a Task

View All Settings

Retention Policies

Set Retention Policy

Scheduler Initialization

Startup Log

Monitoring Task Execution

Last Run Information

Example Result Messages

Audit Trail

Troubleshooting

Best Practices

Backup Strategy

Retention Tuning

Heartbeat Tuning

Next Steps

Agent Management

Real-Time Monitoring

Get Started

Core Features

Integrations

Deployment

Advanced

​Overview

​Accessing Scheduler Status

​Via API

​Scheduled Tasks

​1. Auto Backup

​2. Auto Cleanup

​3. Agent Heartbeat Check

​4. Webhook Retry

​5. Claude Session Scan

​Task Configuration

​Enable a Task

​Disable a Task

​View All Settings

​Retention Policies

​Set Retention Policy

​Scheduler Initialization

​Startup Log

​Monitoring Task Execution

​Last Run Information

​Example Result Messages

​Audit Trail

​Troubleshooting

​Best Practices

​Backup Strategy

​Retention Tuning

​Heartbeat Tuning

​Next Steps

Agent Management

Real-Time Monitoring

Overview

Accessing Scheduler Status

Via API

Scheduled Tasks

1. Auto Backup

2. Auto Cleanup

3. Agent Heartbeat Check

4. Webhook Retry

5. Claude Session Scan

Task Configuration

Enable a Task

Disable a Task

View All Settings

Retention Policies

Set Retention Policy

Scheduler Initialization

Startup Log

Monitoring Task Execution

Last Run Information

Example Result Messages

Audit Trail

Troubleshooting

Best Practices

Backup Strategy

Retention Tuning

Heartbeat Tuning

Next Steps