Filesystem Analysis & Disk Cleanup

Filesystem Analysis & Disk Cleanup provides deep visibility into what is consuming disk space across your fleet and gives you safe, auditable tools to reclaim it. The system combines a parallel-scanning agent worker pool, resumable scan state, and a preview-before-execute cleanup workflow to help administrators identify and resolve disk space issues at scale — without risking accidental data loss.

The feature operates in two phases: analysis (scan the filesystem and build a snapshot of what is consuming space) and cleanup (preview safe candidates, then execute deletion of approved items). Both phases are available through the REST API, the dashboard UI, and the AI assistant.

Note

Filesystem analysis endpoints require authentication with a role that includes the devices.read permission for viewing snapshots and devices.execute for triggering scans and executing cleanup. All operations are audit-logged with the action type, path, scan mode, and byte counts.

---

Overview

Disk space exhaustion is one of the most common and disruptive issues in managed fleets. A single device running out of disk can cause application crashes, failed updates, corrupted databases, and user complaints. Across a fleet of thousands of devices, the problem multiplies — temp files accumulate silently, browser caches grow unchecked, old downloads pile up, and log files go unrotated.

Filesystem Analysis addresses this by:

• Scanning deeply with a parallel worker pool that can traverse millions of filesystem entries efficiently.
• Resuming interrupted scans so that long-running analysis on large volumes is not lost if the agent restarts or the connection drops.
• Categorizing disk usage into actionable groups: largest files, largest directories, temp file accumulation, old downloads, unrotated logs, trash usage, and duplicate candidates.
• Providing safe cleanup with a strict preview-then-execute workflow that only targets known-safe categories.

---

Deep Filesystem Scan

How Scanning Works

A filesystem scan is initiated by sending a POST request to the scan endpoint with a target path and optional configuration. The API queues a filesystem_analysis command to the agent via WebSocket (preferred for immediate dispatch) or the command queue.

The agent-side scanner uses a worker pool to parallelize directory traversal. Multiple goroutines walk the filesystem concurrently, each processing a subtree and reporting results back to a coordinator. This is critical for scanning large volumes — a serial scan of a 2TB disk with millions of files can take over an hour, while a parallelized scan with 8-16 workers can complete in minutes.

Scan Strategies

The system supports three scan strategies that control how much of the filesystem is traversed:

| Strategy | Behavior | When to Use | |----------|----------|-------------| | baseline | Full recursive scan from the specified path. Scans every directory up to maxDepth. | First scan on a device, or when disk usage has changed significantly. | | incremental | Scans only “hot directories” — directories that changed significantly since the last baseline. | Routine follow-up scans to detect new accumulation without rescanning the entire volume. | | auto | The API automatically selects baseline or incremental based on scan state. | Default. Recommended for most use cases. |

When using auto strategy, the API evaluates the following conditions to determine the scan mode:

1. If the scan targets a non-root path (not C:\ or /), a baseline scan is always used.

2. If a previous scan was interrupted and checkpoint data exists, a baseline scan resumes from the checkpoint.

3. If no baseline has ever been completed for this device, a baseline scan is started.

4. If the current disk usage percentage has changed by more than 3% since the last baseline, a baseline scan is triggered.

5. If hot directories exist from the previous scan, an incremental scan targets only those directories.

Resumable State

Long-running baseline scans store checkpoint data in the device_filesystem_scan_state table. The checkpoint records which directories have been scanned and which are still pending. If a scan is interrupted (agent restart, network drop, timeout), the next scan with auto or baseline strategy will automatically resume from the checkpoint rather than starting over.

The scan state table tracks:

| Field | Type | Description | |-------|------|-------------| | deviceId | UUID | Primary key. One state record per device. | | lastRunMode | string | baseline or incremental. | | lastBaselineCompletedAt | timestamp | When the last full baseline scan finished. | | lastDiskUsedPercent | real | Disk usage percentage at the time of the last baseline. Used to decide when a full rescan is needed. | | checkpoint | JSONB | Pending directories and depth information for resume. | | aggregate | JSONB | Accumulated scan results from completed subtrees. | | hotDirectories | JSONB | Directories identified as high-churn for incremental scans (up to 24). |

Scan Configuration

The scan endpoint accepts the following parameters:

POST /api/v1/devices/:deviceId/filesystem/scan
Content-Type: application/json

{
  "path": "C:\\",
  "strategy": "auto",
  "maxDepth": 32,
  "topFiles": 50,
  "topDirs": 30,
  "maxEntries": 5000000,
  "workers": 8,
  "timeoutSeconds": 300,
  "followSymlinks": false
}

| Field | Type | Default | Description | |-------|------|---------|-------------| | path | string | — | Absolute path to scan. Required. Max 2048 characters. | | strategy | enum | auto | Scan strategy: auto, baseline, or incremental. | | maxDepth | number | — | Maximum directory depth to traverse (1-64). | | topFiles | number | — | Number of largest files to return (1-500). | | topDirs | number | — | Number of largest directories to return (1-200). | | maxEntries | number | — | Maximum filesystem entries to scan (1,000 to 25,000,000). | | workers | number | — | Number of parallel scan workers (1-32). | | timeoutSeconds | number | 300 (baseline) / 120 (incremental) | Scan timeout in seconds (5-900). | | followSymlinks | boolean | — | Whether to follow symbolic links during traversal. |

The response returns a 202 Accepted with the command ID and scan mode:

{
  "success": true,
  "data": {
    "commandId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "queued",
    "createdAt": "2026-02-20T14:30:00.000Z",
    "scanMode": "baseline",
    "strategy": "auto"
  }
}

---

Filesystem Snapshots

When a scan completes, the results are saved as a filesystem snapshot in the device_filesystem_snapshots table. Snapshots are immutable records of the filesystem state at a point in time.

Snapshot Contents

| Field | Type | Description | |-------|------|-------------| | id | UUID | Unique snapshot identifier. | | deviceId | UUID | The device that was scanned. | | capturedAt | timestamp | When the snapshot was created. | | trigger | enum | on_demand (user-initiated) or threshold (automatic). | | partial | boolean | true if the scan was interrupted or incomplete. | | summary | JSONB | Aggregate statistics (files scanned, dirs scanned, bytes scanned, max depth, permission denied count). | | largestFiles | JSONB | Top largest files by size (up to 50). | | largestDirs | JSONB | Top largest directories by size (up to 30). | | tempAccumulation | JSONB | Temporary file accumulation by category (bytes per category). | | oldDownloads | JSONB | Files in download directories that have not been accessed recently (up to 200). | | unrotatedLogs | JSONB | Log files that have grown large without rotation (up to 200). | | trashUsage | JSONB | Files in trash/recycle bin (up to 16). | | duplicateCandidates | JSONB | Files that appear to be duplicates based on size and name (up to 200). | | cleanupCandidates | JSONB | All items eligible for safe cleanup (up to 1,000). | | errors | JSONB | Errors encountered during scanning (permission denied, etc., up to 200). |

Viewing the Latest Snapshot

GET /api/v1/devices/:deviceId/filesystem

Returns the most recent snapshot for the device. The response restructures the snapshot data for readability:

{
  "data": {
    "id": "snapshot-uuid",
    "deviceId": "device-uuid",
    "capturedAt": "2026-02-20T14:35:00.000Z",
    "trigger": "on_demand",
    "partial": false,
    "scanMode": "baseline",
    "path": "C:\\",
    "summary": {
      "filesScanned": 1250000,
      "dirsScanned": 85000,
      "bytesScanned": 450000000000,
      "maxDepthReached": 24,
      "permissionDeniedCount": 12
    },
    "topLargestFiles": [...],
    "topLargestDirectories": [...],
    "tempAccumulation": [
      { "category": "browser_cache", "bytes": 2500000000 },
      { "category": "temp_files", "bytes": 1800000000 }
    ],
    "oldDownloads": [...],
    "unrotatedLogs": [...],
    "trashUsage": [...],
    "duplicateCandidates": [...],
    "cleanupCandidates": [...],
    "errors": []
  }
}

Snapshot Merging

When incremental scans run after a baseline, the results are merged with the existing snapshot data. The merge logic:

• Accumulates summary counts (files scanned, dirs scanned, bytes scanned, permission denied count).
• Takes the maximum for max depth reached.
• Deduplicates largest files and directories by path, keeping the entry with the larger size.
• Merges temp accumulation by category, summing byte counts.
• Deduplicates cleanup candidates, old downloads, unrotated logs, and trash entries by path.
• Concatenates error lists up to a cap of 200.

---

Disk Cleanup

Disk cleanup follows a strict two-phase workflow: preview first, then execute. This ensures that no files are deleted without explicit review.

Safe Cleanup Categories

Only items in the following categories are eligible for automated cleanup:

| Category | Description | Examples | |----------|-------------|----------| | temp_files | Operating system and application temporary files. | %TEMP%, /tmp, app-specific temp directories. | | browser_cache | Web browser cache files. | Chrome, Firefox, Edge, Safari cache directories. | | package_cache | Package manager caches. | npm, pip, Homebrew, Chocolatey, NuGet cache directories. | | trash | Files in the trash or recycle bin. | Windows Recycle Bin, macOS Trash, Linux trash directories. |

Caution

Items outside these four categories are never included in cleanup operations, even if they appear in the snapshot’s cleanupCandidates list. Each candidate must have both safe: true and belong to a recognized safe category to be eligible.

Preview Phase

The preview builds a cleanup plan from the latest filesystem snapshot without touching any files on the device.

POST /api/v1/devices/:deviceId/filesystem/cleanup-preview
Content-Type: application/json

{
  "categories": ["temp_files", "browser_cache"]
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | categories | array | No | Filter to specific categories. If omitted, all safe categories are included. Max 10 entries. |

The response includes the preview plan and creates a cleanup run record with status previewed:

{
  "success": true,
  "data": {
    "cleanupRunId": "run-uuid",
    "snapshotId": "snapshot-uuid",
    "estimatedBytes": 4300000000,
    "candidateCount": 156,
    "categories": [
      { "category": "temp_files", "count": 89, "estimatedBytes": 1800000000 },
      { "category": "browser_cache", "count": 67, "estimatedBytes": 2500000000 }
    ],
    "candidates": [
      {
        "path": "C:\\Users\\admin\\AppData\\Local\\Temp\\old_installer.exe",
        "category": "temp_files",
        "sizeBytes": 450000000,
        "safe": true,
        "reason": "Temporary file older than 30 days",
        "modifiedAt": "2026-01-15T10:00:00.000Z"
      }
    ]
  }
}

Execute Phase

After reviewing the preview, submit the specific paths you want to delete. Only paths that appear in the latest preview as safe candidates are accepted.

POST /api/v1/devices/:deviceId/filesystem/cleanup-execute
Content-Type: application/json

{
  "paths": [
    "C:\\Users\\admin\\AppData\\Local\\Temp\\old_installer.exe",
    "C:\\Users\\admin\\AppData\\Local\\Google\\Chrome\\User Data\\Default\\Cache"
  ]
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | paths | array | Yes | Paths to delete. Must be from the latest previewable candidates. Min 1, max 200 entries. Max 4096 characters per path. |

The API validates each path against the current snapshot’s safe cleanup candidates. Paths not present in the candidate list are silently excluded. For each valid path, a file_delete command is dispatched to the agent with recursive: true.

The response reports per-path results:

{
  "success": true,
  "data": {
    "cleanupRunId": "run-uuid",
    "status": "executed",
    "bytesReclaimed": 4100000000,
    "selectedCount": 2,
    "failedCount": 0,
    "actions": [
      {
        "path": "C:\\Users\\admin\\AppData\\Local\\Temp\\old_installer.exe",
        "category": "temp_files",
        "sizeBytes": 450000000,
        "status": "completed"
      },
      {
        "path": "C:\\Users\\admin\\AppData\\Local\\Google\\Chrome\\User Data\\Default\\Cache",
        "category": "browser_cache",
        "sizeBytes": 3650000000,
        "status": "completed"
      }
    ]
  }
}

If all cleanup actions fail, the run status is failed. If at least one succeeds, the status is executed.

---

AI Integration

The AI assistant provides two tools for filesystem analysis and cleanup.

analyze_disk_usage (Tier 1)

A read-only tool that retrieves the latest filesystem snapshot for a device and explains what is consuming disk space. It can optionally trigger a fresh scan.

| Parameter | Type | Description | |-----------|------|-------------| | deviceId | string (UUID) | The device to analyze. Required. | | refresh | boolean | If true, trigger a new scan before returning results. | | path | string | Root path to scan (default: OS root). | | maxDepth | number | Maximum scan depth (1-64). | | topFiles | number | Number of largest files to return (1-500). | | topDirs | number | Number of largest directories to return (1-200). | | maxEntries | number | Maximum filesystem entries to scan (1,000-25,000,000). | | workers | number | Number of parallel scan workers (1-32). | | timeoutSeconds | number | Scan timeout (5-900 seconds). | | maxCandidates | number | Maximum cleanup candidates to return (1-200). |

The AI uses this tool to answer questions like “What is using disk space on this device?”, “Why is the C: drive full?”, and “Show me the largest files on device X.”

disk_cleanup (Tier 1 preview / Tier 3 execute)

A dual-tier tool. Preview mode is Tier 1 (auto-executed, read-only). Execute mode is Tier 3 (requires human approval before deleting files).

| Parameter | Type | Description | |-----------|------|-------------| | deviceId | string (UUID) | The device to clean up. Required. | | action | enum | preview or execute. Required. | | categories | array | Filter cleanup to specific categories. Optional. | | paths | array | Specific paths to delete (required for execute). Min 1, max 200. | | maxCandidates | number | Maximum candidates to return in preview (1-200). |

Tip

The AI automatically chains these tools: it first calls analyze_disk_usage to understand the problem, then uses disk_cleanup with action: "preview" to show what can be cleaned, and finally (with user approval) calls disk_cleanup with action: "execute" to perform the cleanup. You can ask it to do this in a single conversation turn.

---

Cleanup Targets

The filesystem scanner identifies several categories of reclaimable space. Here is what each category covers and where the scanner looks.

Temporary Files (temp_files)

Windows

• %TEMP% (user temp directory)
• C:\Windows\Temp (system temp directory)
• C:\Windows\Prefetch (prefetch cache)
• Application-specific temp directories

macOS

• /tmp and /private/tmp
• ~/Library/Caches (per-user caches)
• /Library/Caches (system caches)

Linux

• /tmp and /var/tmp
• Application-specific temp directories in /var/cache

Browser Caches (browser_cache)

Cache directories for all major browsers:

• Chrome: User Data/Default/Cache, Code Cache, Service Worker
• Firefox: cache2 directory in profile
• Edge: Same structure as Chrome (Chromium-based)
• Safari: ~/Library/Caches/com.apple.Safari

Package Manager Caches (package_cache)

• npm: ~/.npm/_cacache
• pip: ~/.cache/pip (Linux/macOS) or %LOCALAPPDATA%\pip\cache (Windows)
• Homebrew: ~/Library/Caches/Homebrew
• Chocolatey: C:\ProgramData\chocolatey\cache
• NuGet: ~/.nuget/packages

Trash and Recycle Bin (trash)

• Windows: C:\$Recycle.Bin per-user directories
• macOS: ~/.Trash
• Linux: ~/.local/share/Trash

Additional Detected Items (Not Auto-Cleaned)

The scanner also detects the following, which appear in the snapshot but are not eligible for automated cleanup:

• Old downloads: Files in download directories older than a configurable threshold.
• Unrotated logs: Log files that have grown beyond expected sizes.
• Duplicate candidates: Files with matching sizes and names in different locations.
• Large files: The top N largest individual files on the volume.

These items require manual review and are surfaced in the snapshot for informational purposes.

---

Database Schema

Filesystem Snapshots

Table: device_filesystem_snapshots

| Column | Type | Description | |--------|------|-------------| | id | UUID | Primary key. | | device_id | UUID | Foreign key to devices. | | captured_at | timestamp | When the snapshot was created. | | trigger | enum | on_demand or threshold. | | partial | boolean | Whether the scan was incomplete. | | summary | JSONB | Aggregate scan statistics. | | largest_files | JSONB | Top largest files. | | largest_dirs | JSONB | Top largest directories. | | temp_accumulation | JSONB | Temp file accumulation by category. | | old_downloads | JSONB | Old files in download directories. | | unrotated_logs | JSONB | Large unrotated log files. | | trash_usage | JSONB | Trash/recycle bin contents. | | duplicate_candidates | JSONB | Potential duplicate files. | | cleanup_candidates | JSONB | All safe cleanup candidates. | | errors | JSONB | Scan errors. | | raw_payload | JSONB | Complete raw agent response. |

Indexed on (device_id, captured_at) for efficient latest-snapshot queries.

Cleanup Runs

Table: device_filesystem_cleanup_runs

| Column | Type | Description | |--------|------|-------------| | id | UUID | Primary key. | | device_id | UUID | Foreign key to devices. | | requested_by | UUID | Foreign key to users (who initiated the cleanup). | | requested_at | timestamp | When the cleanup was requested. | | approved_at | timestamp | When the cleanup was approved for execution (null for preview-only runs). | | plan | JSONB | The cleanup plan (snapshot ID, categories, preview data). | | executed_actions | JSONB | Per-path execution results. | | bytes_reclaimed | bigint | Total bytes reclaimed by the cleanup. | | status | enum | previewed, executed, or failed. | | error | text | Error message if the run failed. |

Indexed on (device_id, requested_at) for history queries.

Scan State

Table: device_filesystem_scan_state

| Column | Type | Description | |--------|------|-------------| | device_id | UUID | Primary key. Foreign key to devices. One row per device. | | last_run_mode | text | baseline or incremental. | | last_baseline_completed_at | timestamp | When the last full baseline finished. | | last_disk_used_percent | real | Disk usage at last baseline (for delta detection). | | checkpoint | JSONB | Pending directories for scan resume. | | aggregate | JSONB | Accumulated partial results. | | hot_directories | JSONB | High-churn directories for incremental scans. |

---

API Reference

All filesystem endpoints are prefixed with /api/v1/devices/:deviceId. Replace :deviceId with a valid device UUID.

| Method | Path | Description | Permission | |--------|------|-------------|------------| | GET | /devices/:id/filesystem | Get latest filesystem analysis snapshot | devices.read | | POST | /devices/:id/filesystem/scan | Trigger a filesystem scan | devices.execute | | POST | /devices/:id/filesystem/cleanup-preview | Preview safe cleanup candidates | devices.read | | POST | /devices/:id/filesystem/cleanup-execute | Execute cleanup on approved paths | devices.execute |

---

Troubleshooting

”No filesystem analysis available yet” (404)

No snapshot exists for this device. The device has not been scanned yet. Trigger a scan with POST /devices/:id/filesystem/scan and wait for it to complete before querying the snapshot.

”No filesystem snapshot available. Run a scan first.” (404 on cleanup-preview)

The cleanup preview requires an existing snapshot to build the candidate list from. Run a filesystem scan first, then retry the preview.

Scan command returns 502 or times out

Large filesystem scans can exceed the default command timeout. Try:

• Increasing timeoutSeconds (up to 900 seconds / 15 minutes).
• Reducing maxEntries to limit the scan scope.
• Reducing maxDepth to avoid deeply nested directory trees.
• Scanning a subdirectory instead of the root path.

The scan uses resumable state, so a timed-out baseline scan will resume from its checkpoint on the next attempt.

Cleanup preview returns zero candidates

The preview filters candidates by two criteria: the safe flag must be true AND the category must be one of the four safe categories (temp_files, browser_cache, package_cache, trash). If the snapshot contains cleanup candidates but the preview returns none, the candidates may be in non-safe categories (e.g., old downloads, unrotated logs) that require manual review.

Also verify that the categories filter in your request matches the categories present in the snapshot’s candidates.

”No valid cleanup paths selected from latest previewable candidates” (400)

The paths submitted to the execute endpoint do not match any current safe cleanup candidates. This can happen if:

• A new scan ran between the preview and execute, changing the candidate list.
• The paths were manually constructed rather than copied from a preview response.
• The candidates’ safe flag was false (items outside safe categories are excluded).

Re-run the preview and use paths from the fresh response.

Cleanup actions partially failed

The cleanup execute response reports per-path status. Individual paths can fail if:

• The file was already deleted between preview and execute.
• The agent does not have permission to delete the file (e.g., a file locked by a running process).
• The path is on a read-only filesystem.

The overall run status is executed if at least one path succeeded, or failed if every path failed. The bytesReclaimed field reflects only the successfully deleted paths.

Incremental scan returns minimal results

Incremental scans only traverse hot directories identified by the previous baseline. If no hot directories were detected (the disk is relatively stable), the incremental scan has little to scan. This is expected behavior. Run a baseline scan to get a comprehensive view.

Scan shows “partial: true” in the snapshot

The scan was interrupted before completing. This can be caused by agent restart, network disconnection, or timeout. The partial snapshot contains valid data for the portions that were scanned. Run another scan to resume from the checkpoint — the system will merge results with the partial data.

Permission denied errors in scan results

The agent process may not have permission to read certain directories (e.g., other users’ home directories, system-protected paths). These are logged in the snapshot’s errors array with the path and error type. Running the agent as root/SYSTEM reduces permission errors but is not always necessary — the most valuable disk usage data is typically in user-accessible directories.