cleveragents-core/docs/reference/cleanup.md

Cleanup / Garbage Collection

The agents cleanup command group provides garbage collection for stale platform resources: sandboxes, checkpoints, sessions, logs, and backups. All operations respect configurable retention policies and protect active resources from accidental deletion.

---

Subcommands

agents cleanup scan

Dry-run scan that identifies stale resources without deleting anything. Prints a per-resource summary table and lists every item that would be cleaned.

agents cleanup scan

agents cleanup purge

Remove stale resources based on retention policies.

agents cleanup purge [--dry-run] [--all] [--yes|-y]

Flag	Default	Description
--dry-run	false	Report what would be removed without deleting.
--all	false	Purge all resource types (sandboxes, checkpoints, sessions, logs, backups). Without this flag, only sandboxes and checkpoints are purged.
--yes, -y	false	Skip the interactive confirmation prompt.

agents cleanup status

Display current retention policy settings.

agents cleanup status

---

Resource Types

Sandboxes

Sandbox directories live in the system temp directory with prefixes ca-sandbox- and ca-cow-sandbox-. A sandbox is considered stale when its modification time exceeds cleanup_sandbox_max_age_hours. Sandboxes linked to a currently-running plan are skipped and logged.

Checkpoints

LangGraph checkpoint files (checkpoint_*.json) reside under <data_dir>/checkpoints/<plan_id>/. When a plan accumulates more checkpoints than cleanup_checkpoint_max_per_plan, the oldest files are pruned while always keeping the first and most recent checkpoint.

Sessions

Sessions in the SQLite database that have not been updated for longer than cleanup_session_inactivity_days are eligible for removal. Session cleanup is only performed when --all is passed to purge.

Logs

Log files (*.log) under <log_dir> older than cleanup_log_retention_days are removed during an --all purge.

Backups

Backup files under <data_dir>/backups/ older than cleanup_backup_retention_days are removed during an --all purge.

---

Configuration

All retention policies are configurable via environment variables or the Settings model.

Setting	Env Variable	Default	Description
cleanup_sandbox_max_age_hours	CLEVERAGENTS_CLEANUP_SANDBOX_MAX_AGE_HOURS	48	Max sandbox age in hours before eligibility.
cleanup_checkpoint_max_per_plan	CLEVERAGENTS_CHECKPOINT_MAX	50	Max checkpoints retained per plan.
cleanup_session_inactivity_days	CLEVERAGENTS_CLEANUP_SESSION_INACTIVITY_DAYS	30	Days of inactivity before session is stale.
cleanup_log_retention_days	CLEVERAGENTS_LOG_RETENTION_DAYS	30	Days to retain log files.
cleanup_backup_retention_days	CLEVERAGENTS_BACKUP_RETENTION_DAYS	7	Days to retain backup snapshots.
cleanup_schedule	CLEVERAGENTS_CLEANUP_SCHEDULE	manual	manual (user-initiated) or auto (stub).

These correspond to the specification config keys:

• sandbox.cleanup → manual (MVP)
• sandbox.checkpoint.max-per-plan → 50
• core.log.retention-days → 30
• core.backup.retention-days → 7

---

Safety

• Active plan protection: Sandboxes linked to a running plan ID are never deleted. The skipped items and reasons appear in the report.
• Confirmation prompt: purge requires interactive confirmation unless --yes is passed.
• Dry-run: Both scan and purge --dry-run preview cleanup without side effects.
• Checkpoint preservation: The first and most recent checkpoint for each plan are always retained, even when pruning excess files.

---

Examples

Scan for stale resources:

$ agents cleanup scan
Cleanup Scan Results (dry-run)

  Mode: Dry-run
  Sandboxes        scanned=4  to remove=2  skipped=1
  Checkpoints      scanned=120  to remove=15  skipped=0
  Sessions         scanned=0  to remove=0  skipped=0
  Logs             scanned=8  to remove=3  skipped=0
  Backups          scanned=5  to remove=2  skipped=0

Stale items found:
  [sandbox] /tmp/ca-sandbox-plan123-abcd (3 days old)
  [checkpoint] .cleveragents/checkpoints/plan456/checkpoint_003.json (excess)
  ...

Purge only sandboxes and checkpoints (default):

$ agents cleanup purge --yes
Cleanup Complete

  Mode: Purge
  Sandboxes        scanned=4  removed=2  skipped=1
  Checkpoints      scanned=120  removed=15  skipped=0
  Sessions         scanned=0  removed=0  skipped=0
  Logs             scanned=0  removed=0  skipped=0
  Backups          scanned=0  removed=0  skipped=0

Purge all resource types with dry-run preview:

$ agents cleanup purge --all --dry-run

View current retention settings:

$ agents cleanup status
Cleanup Retention Policies

  Sandbox max age:        48 hours
  Checkpoint max/plan:    50
  Session inactivity:     30 days
  Log retention:          30 days
  Backup retention:       7 days
  Schedule:               manual