# What Is the Garbage Collection Manager in OpenCTI and How to Configure It

> Discover the OpenCTI garbage collection manager, a background process that deletes soft-deleted entities. Learn how to configure retention periods and batch processing for efficient database management.

- Repository: [OpenCTI Platform/opencti](https://github.com/opencti-platform/opencti)
- Tags: how-to-guide
- Published: 2026-02-19

---

**The garbage collection manager in OpenCTI is a background cron-driven process that permanently erases soft-deleted entities from the trash after a configurable retention period, processing records in batches to avoid database contention.**

The garbage collection manager ensures that deleted entities in OpenCTI do not accumulate indefinitely in your database. When users delete objects through the interface, OpenCTI creates **DeleteOperation** records that hold the data in a trash state. The manager runs continuously to purge these records once they exceed the retention threshold, freeing storage and maintaining compliance with data retention policies.

## What the Garbage Collection Manager Does

The manager executes as a **lock-protected background task** registered via `registerManager(GARBAGE_COLLECTION_MANAGER_DEFINITION)` in [`src/manager/garbageCollectionManager.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/src/manager/garbageCollectionManager.ts). Its core responsibilities include:

- **Scheduled Execution**: Runs at fixed intervals (default every 60,000 milliseconds) to query for expired delete operations.
- **Batch Processing**: Fetches up to **BATCH_SIZE** records (default 10,000) per execution cycle to prevent memory exhaustion.
- **Permanent Deletion**: Invokes `confirmDelete` from [`src/modules/deleteOperation/deleteOperation-domain.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/src/modules/deleteOperation/deleteOperation-domain.ts) to physically remove data older than **DELETED_RETENTION_DAYS** (default 7 days).
- **Fault Isolation**: Logs errors for individual deletion failures without halting the entire batch operation.

The manager only activates when both the global trash feature and the manager itself are enabled, as defined by the condition `enabledByConfig: TRASH_ENABLED && GARBAGE_COLLECTION_MANAGER_ENABLED` in the source.

## Architecture and Source Code Locations

### Manager Registration and Handler

The garbage collection manager integrates into OpenCTI's platform architecture through several key files:

- **[`src/manager/garbageCollectionManager.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/src/manager/garbageCollectionManager.ts)**: Contains the `garbageCollectionHandler` function and the `GARBAGE_COLLECTION_MANAGER_DEFINITION` object that specifies the cron schedule, lock key, and enablement conditions.
- **[`src/manager/index.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/src/manager/index.ts)**: Loads the garbage collection module, ensuring it becomes part of the platform's `ManagerModule` registry during startup.
- **`src/utils/access`**: Provides the execution context identifier (`garbage_collection_manager`) used for permission checks during deletion operations.

### Domain Logic and Data Flow

The actual deletion workflow relies on the delete operation domain layer:

1. **`findOldDeleteOperations`** (in [`src/modules/deleteOperation/deleteOperation-domain.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/src/modules/deleteOperation/deleteOperation-domain.ts)): Queries the database for DeleteOperation records where the deletion timestamp exceeds `DELETED_RETENTION_DAYS`.
2. **`confirmDelete`**: Permanently removes the entity data and associated relationships from the database.
3. **Redis Locking**: The manager uses a distributed lock (`lock_key`) to prevent concurrent execution across clustered OpenCTI instances.

## Configuring the Garbage Collection Manager

All configuration parameters reside under the `garbage_collection_manager` key in the platform configuration hierarchy.

### Default Configuration Values

The baseline settings are defined in [`config/default.json`](https://github.com/OpenCTI-Platform/opencti/blob/main/config/default.json):

```json
"garbage_collection_manager": {
  "enabled": true,
  "lock_key": "garbage_collection_manager_lock",
  "batch_size": 10000,
  "interval": 60000,
  "deleted_retention_days": 7
}

```

### Environment Variable Overrides

You can override defaults using environment variables prefixed with `GARBAGE_COLLECTION_MANAGER__`:

```bash
export GARBAGE_COLLECTION_MANAGER__ENABLED=false
export GARBAGE_COLLECTION_MANAGER__INTERVAL=300000
export GARBAGE_COLLECTION_MANAGER__DELETED_RETENTION_DAYS=30
export GARBAGE_COLLECTION_MANAGER__BATCH_SIZE=5000

```

### YAML Configuration Example

For Docker Compose or Kubernetes deployments, specify settings in your [`config.yml`](https://github.com/OpenCTI-Platform/opencti/blob/main/config.yml) or environment block:

```yaml
garbage_collection_manager:
  enabled: true
  interval: 120000        # Run every 2 minutes

  batch_size: 2000        # Process 2,000 items per batch

  deleted_retention_days: 14
  lock_key: "garbage_collection_manager_lock"

```

Note that setting `app:trash:enabled` to `false` globally disables the garbage collection manager regardless of its specific configuration, as the manager depends on the trash feature being active.

## Manual Execution for Debugging

You can trigger the garbage collection process manually during development or troubleshooting by invoking the handler directly:

```typescript
import { garbageCollectionHandler } from './src/manager/garbageCollectionManager';

(async () => {
  console.log('Starting manual garbage collection...');
  await garbageCollectionHandler();
  console.log('Garbage collection completed.');
})();

```

This bypasses the cron scheduler and Redis locking mechanisms, so use it only in single-instance development environments.

## Summary

- The **garbage collection manager** automatically purges soft-deleted entities from OpenCTI's trash after the retention period expires.
- Configuration occurs via [`config/default.json`](https://github.com/OpenCTI-Platform/opencti/blob/main/config/default.json), environment variables with the `GARBAGE_COLLECTION_MANAGER__` prefix, or YAML files.
- Default settings retain deleted items for **7 days**, processing **10,000 records per minute**.
- The manager requires both the global trash feature (`app:trash:enabled`) and its own enabled flag to run.
- Source code is located primarily in [`src/manager/garbageCollectionManager.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/src/manager/garbageCollectionManager.ts) and [`src/modules/deleteOperation/deleteOperation-domain.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/src/modules/deleteOperation/deleteOperation-domain.ts).

## Frequently Asked Questions

### How often does the garbage collection manager run in OpenCTI?

By default, the manager executes every **60,000 milliseconds (1 minute)**. You can adjust this interval by setting the `interval` configuration parameter (in milliseconds) via environment variables or YAML configuration. The manager uses a Redis lock to ensure only one instance runs the cleanup job in clustered deployments.

### What happens if I disable the garbage collection manager?

When disabled, OpenCTI retains all **DeleteOperation** records indefinitely in the trash, causing your database to grow continuously. Soft-deleted entities remain recoverable but consume storage space. Disabling the manager does not affect the ability to manually restore items from trash during the retention period, but it prevents automatic permanent deletion.

### How do I extend the trash retention period beyond the default 7 days?

Set the `deleted_retention_days` parameter to your desired value. For example, export `GARBAGE_COLLECTION_MANAGER__DELETED_RETENTION_DAYS=30` to retain deleted items for 30 days before permanent erasure. Changes take effect on the next scheduled run; previously expired records will be purged if they exceed the new threshold.

### Where can I find the complete configuration reference for the garbage collection manager?

The official configuration documentation resides in [`docs/docs/deployment/configuration.md`](https://github.com/OpenCTI-Platform/opencti/blob/main/docs/docs/deployment/configuration.md) (lines 425-429), which lists all available parameters including `enabled`, `lock_key`, `batch_size`, `interval`, and `deleted_retention_days`. The implementation details and default values are defined in [`src/manager/garbageCollectionManager.ts`](https://github.com/OpenCTI-Platform/opencti/blob/main/src/manager/garbageCollectionManager.ts) and [`config/default.json`](https://github.com/OpenCTI-Platform/opencti/blob/main/config/default.json) within the opencti-graphql package.