Commands & Config

The Breeze agent supports 120+ commands organized into 30+ categories. Commands are sent from the API to agents over WebSocket, each with an action string and an optional JSON payload.

Command Flow

Dashboard → POST /devices/:id/commands
         → BullMQ job created
         → WebSocket message sent to agent
         → Agent executes command
         → Agent sends result via WebSocket
         → Result stored in database
         → Dashboard receives real-time update

Commands with a term- prefix bypass the database queue and are sent directly over WebSocket for real-time terminal sessions.

Command Result Format

Every command returns a standard result envelope:

| Field | Type | Description | |---|---|---| | status | string | completed, failed, or timeout | | exitCode | int | Exit code (0 for success) | | stdout | string | JSON-encoded result data or script output | | stderr | string | Error output (scripts only) | | error | string | Error message when status is failed | | durationMs | int64 | Execution time in milliseconds |

Process Management

Enumerate, inspect, and terminate running processes. Cross-platform (Windows, macOS, Linux).

| Action | Description | Key Payload Fields | |---|---|---| | list_processes | List running processes (paginated) | page, limit, search, sortBy, sortDesc | | get_process | Get details for a specific process | pid (required) | | kill_process | Terminate a process by PID | pid (required), force |

`list_processes`

| Param | Type | Default | Description | |---|---|---|---| | page | int | 1 | Page number | | limit | int | 50 | Results per page (max 500) | | search | string | "" | Filter by name, user, command line, or PID | | sortBy | string | "cpu" | Sort field: cpu, memory, pid, name, user | | sortDesc | bool | true | Sort descending |

Returns ProcessListResponse with processes[], total, page, limit, totalPages.

`get_process`

| Param | Type | Required | Description | |---|---|---|---| | pid | int | Yes | Process ID to inspect |

Returns a single ProcessInfo object with pid, name, user, cpuPercent, memoryMb, status, commandLine, parentPid, threads, createTime.

`kill_process`

| Param | Type | Default | Description | |---|---|---|---| | pid | int | Required | Process ID to terminate | | force | bool | false | If true, sends SIGKILL instead of SIGTERM |

Service Management

List, inspect, start, stop, and restart system services. Platform-aware: uses systemd on Linux, launchd on macOS, and the Windows Service Control Manager.

| Action | Description | Key Payload Fields | |---|---|---| | list_services | List system services (paginated) | page, limit, search, status | | get_service | Get details for a specific service | name (required) | | start_service | Start a stopped service | name (required) | | stop_service | Stop a running service | name (required) | | restart_service | Restart a service | name (required) |

`list_services`

| Param | Type | Default | Description | |---|---|---|---| | page | int | 1 | Page number | | limit | int | 50 | Results per page (max 500) | | search | string | "" | Filter by service name | | status | string | "" | Filter by status (e.g. Running, Stopped) |

Returns ServiceListResponse with services[], each containing name, displayName, status, startupType, account, path, description.

`get_service` / `start_service` / `stop_service` / `restart_service`

| Param | Type | Required | Description | |---|---|---|---| | name | string | Yes | Service name (e.g. sshd, nginx, wuauserv) |

Event Logs (Windows)

Query Windows Event Logs. Returns stub responses on non-Windows platforms.

| Action | Description | Key Payload Fields | |---|---|---| | event_logs_list | List available event logs | — | | event_logs_query | Query events from a log | logName, level, source, eventId, page, limit | | event_log_get | Get a specific log entry | logName, recordId |

`event_logs_query`

| Param | Type | Default | Description | |---|---|---|---| | logName | string | "System" | Log name (System, Application, Security, etc.) | | level | string | "" | Filter: Information, Warning, Error, Critical | | source | string | "" | Filter by event source | | eventId | int | 0 | Filter by event ID | | page | int | 1 | Page number | | limit | int | 50 | Results per page (max 500) |

`event_log_get`

| Param | Type | Default | Description | |---|---|---|---| | logName | string | "System" | Log name | | recordId | int | 0 | Record ID of the entry |

Scheduled Tasks (Windows)

Manage Windows Task Scheduler tasks. Returns stub responses on non-Windows platforms.

| Action | Description | Key Payload Fields | |---|---|---| | tasks_list | List scheduled tasks (paginated) | folder, search, page, limit | | task_get | Get details for a specific task | path | | task_run | Trigger a task to run immediately | path | | task_enable | Enable a disabled task | path | | task_disable | Disable a task | path | | task_history | Get execution history for a task | path, limit |

`tasks_list`

| Param | Type | Default | Description | |---|---|---|---| | folder | string | "\" | Task Scheduler folder to list | | search | string | "" | Filter by task name | | page | int | 1 | Page number | | limit | int | 50 | Results per page (max 500) |

`task_get` / `task_run` / `task_enable` / `task_disable`

| Param | Type | Required | Description | |---|---|---|---| | path | string | Yes | Full task path (e.g. \Microsoft\Windows\UpdateOrchestrator\Schedule Scan) |

`task_history`

| Param | Type | Default | Description | |---|---|---|---| | path | string | Required | Full task path | | limit | int | 50 | Max entries to return (1-200) |

Registry (Windows)

Read and write Windows Registry keys and values. Returns error stubs on non-Windows platforms.

| Action | Description | Key Payload Fields | |---|---|---| | registry_keys | List subkeys at a registry path | hive, path | | registry_values | List values at a registry path | hive, path | | registry_get | Get a specific registry value | hive, path, name | | registry_set | Set a registry value | hive, path, name, type, data | | registry_delete | Delete a registry value | hive, path, name | | registry_key_create | Create a new registry key | hive, path | | registry_key_delete | Delete a registry key | hive, path |

Common Parameters

| Param | Type | Default | Description | |---|---|---|---| | hive | string | "HKLM" | Registry hive: HKLM, HKCU, HKCR, HKU, HKCC | | path | string | "" | Registry key path (e.g. SOFTWARE\Microsoft\Windows\CurrentVersion) |

`registry_get`

| Param | Type | Default | Description | |---|---|---|---| | hive | string | "HKLM" | Registry hive | | path | string | "" | Key path | | name | string | "" | Value name |

`registry_set`

| Param | Type | Default | Description | |---|---|---|---| | hive | string | "HKLM" | Registry hive | | path | string | "" | Key path | | name | string | "" | Value name | | type | string | "REG_SZ" | Value type: REG_SZ, REG_DWORD, REG_BINARY, REG_EXPAND_SZ, REG_MULTI_SZ, REG_QWORD | | data | string | "" | Value data |

`registry_delete`

| Param | Type | Default | Description | |---|---|---|---| | hive | string | "HKLM" | Registry hive | | path | string | "" | Key path | | name | string | "" | Value name to delete |

System

Power management and session locking. Cross-platform.

| Action | Description | Key Payload Fields | |---|---|---| | reboot | Schedule a system reboot | delay | | shutdown | Schedule a system shutdown | delay | | lock | Lock the current user session | — | | reboot_safe_mode | Reboot into Safe Mode with Networking (Windows only) | delay |

`reboot` / `shutdown`

| Param | Type | Default | Description | |---|---|---|---| | delay | int | 0 | Delay in minutes before executing (0-1440, i.e. max 24 hours) |

Platform behavior:

Windows: Runs shutdown /r /t <seconds> (reboot) or shutdown /s /t <seconds> (shutdown)
Linux/macOS: Runs shutdown -r +<minutes> (reboot) or shutdown -h +<minutes> (shutdown)

`lock`

No payload parameters. Locks the active session:

Windows: rundll32.exe user32.dll,LockWorkStation
macOS: CGSession -suspend
Linux: loginctl lock-session (falls back to dm-tool lock)

`reboot_safe_mode`

Reboot a Windows device into Safe Mode with Networking. Uses bcdedit to set the safe boot flag before initiating a shutdown. If the shutdown command fails, the safe boot flag is automatically cleared to prevent accidental safe mode boots.

| Param | Type | Default | Description | |---|---|---|---| | delay | int | 0 | Delay in minutes before rebooting (0-1440) |

`set_auto_update`

Enable or disable automatic agent self-updates for the device. When disabled, the agent stops pulling and installing new versions on its own; you can still update it explicitly. The setting is written to the agent config and persists across restarts.

| Param | Type | Default | Description | |---|---|---|---| | enabled | bool | — | true to enable auto-update, false to disable |

This command is also exposed directly as POST /devices/:id/auto-update with body { "enabled": <bool> } — useful for re-enabling auto-update on agents that were left with it turned off (for example after a manual or recovery update).

`refresh_inventory`

Ask the agent to collect a fresh hardware/software inventory snapshot immediately instead of waiting for its scheduled run. The dashboard exposes this as the Refresh Inventory button on the device detail page; the API surface is POST /devices/:id/commands with { "type": "refresh_inventory" }.

Duplicates are rejected: while an inventory refresh is already queued or running for a device, a second request returns 409 Conflict with code: "ALREADY_PENDING". The bulk variant (POST /devices/bulk/commands) applies the same check per device and partitions its response into commands (newly issued), skipped (already-pending refreshes, each with the existing commandId), and failed.

File Operations

Browse, read, write, and manage files on the agent filesystem. All paths are cleaned and normalized. Mutating operations are blocked on critical system paths (/, /boot, /proc, /sys, /dev, /bin, /sbin, /usr).

| Action | Description | Key Payload Fields | |---|---|---| | file_list | List directory contents | path | | file_read | Read file contents | path, encoding | | file_write | Write content to a file | path, content, encoding | | file_delete | Delete a file or directory | path, recursive | | file_mkdir | Create a directory | path | | file_rename | Rename or move a file | oldPath, newPath | | filesystem_analysis | Deep filesystem analysis | path, scanMode, maxDepth, topFiles, topDirs, timeoutSeconds |

`file_list`

| Param | Type | Default | Description | |---|---|---|---| | path | string | User home dir | Directory to list |

Returns FileListResponse with entries[], each containing name, path, type (file/directory), size, modified, permissions.

`file_read`

| Param | Type | Default | Description | |---|---|---|---| | path | string | Required | File path to read | | encoding | string | "text" | "text" for UTF-8, "base64" for binary |

`file_write`

| Param | Type | Default | Description | |---|---|---|---| | path | string | Required | File path to write | | content | string | "" | File content | | encoding | string | "text" | "text" or "base64" |

Parent directories are created automatically. Files are written with 0644 permissions.

`file_delete`

| Param | Type | Default | Description | |---|---|---|---| | path | string | Required | File or directory path | | recursive | bool | false | If true, removes directories and all contents. Recursive deletes are blocked on top-level paths (e.g. /home, /var). |

`file_mkdir`

| Param | Type | Required | Description | |---|---|---|---| | path | string | Yes | Directory path to create (with parents) |

`file_rename`

| Param | Type | Required | Description | |---|---|---|---| | oldPath | string | Yes | Source path | | newPath | string | Yes | Destination path |

`filesystem_analysis`

Deep filesystem scan that identifies large files, large directories, duplicate candidates, temp/cache accumulation, old downloads, unrotated logs, trash usage, and safe cleanup candidates.

| Param | Type | Default | Description | |---|---|---|---| | path | string | Required | Root directory to analyze | | scanMode | string | "baseline" | "baseline" (deep) or "incremental" (targeted) | | maxDepth | int | 32 (baseline) / 12 (incremental) | Max directory depth (1-64) | | topFiles | int | 50 | Number of largest files to return (1-500) | | topDirs | int | 30 | Number of largest directories to return (1-200) | | maxEntries | int | 10,000,000 | Max filesystem entries to scan (1,000-25,000,000) | | timeoutSeconds | int | 20 | Scan timeout (5-900 seconds) | | followSymlinks | bool | false | Follow symbolic links | | workers | int | auto | Parallel scan workers (1-32; auto-scaled to CPU count) | | targetDirectories | string[] | — | Specific directories for incremental scans | | checkpoint | object | — | Resume a previously interrupted scan |

The response includes topLargestFiles, topLargestDirectories, tempAccumulation, oldDownloads, unrotatedLogs, trashUsage, duplicateCandidates, cleanupCandidates, and a summary with scan statistics. If the scan is interrupted (timeout or max entries), partial: true is set along with a checkpoint that can be passed to resume.

Terminal

Open interactive remote terminal (PTY) sessions. Terminal commands use the term- prefix for command IDs and bypass the database queue for low-latency communication.

| Action | Description | Key Payload Fields | |---|---|---| | terminal_start | Open a new terminal session | sessionId, cols, rows, shell | | terminal_data | Send input data to a session | sessionId, data | | terminal_resize | Resize a terminal session | sessionId, cols, rows | | terminal_stop | Close and destroy a session | sessionId |

`terminal_start`

| Param | Type | Default | Description | |---|---|---|---| | sessionId | string | Required | Unique session identifier | | cols | int | 80 | Terminal column count | | rows | int | 24 | Terminal row count | | shell | string | "" | Shell to launch (empty = system default) |

`terminal_data`

| Param | Type | Required | Description | |---|---|---|---| | sessionId | string | Yes | Session to write to | | data | string | Yes | Input data (keystrokes, paste content) |

`terminal_resize`

| Param | Type | Default | Description | |---|---|---|---| | sessionId | string | Required | Session to resize | | cols | int | 80 | New column count | | rows | int | 24 | New row count |

`terminal_stop`

| Param | Type | Required | Description | |---|---|---|---| | sessionId | string | Yes | Session to close |

Remote Desktop

Two remote desktop modes are available: WebRTC-based (legacy) and WebSocket-based streaming.

WebRTC (Legacy)

| Action | Description | Key Payload Fields | |---|---|---| | start_desktop | Start a WebRTC desktop session | sessionId, offer, iceServers | | stop_desktop | Stop a WebRTC desktop session | sessionId |

`start_desktop`

| Param | Type | Required | Description | |---|---|---|---| | sessionId | string | Yes | Unique session identifier | | offer | string | Yes | WebRTC SDP offer | | iceServers | array | No | Array of { urls, username, credential } ICE server configs |

Returns { sessionId, answer } where answer is the WebRTC SDP answer.

WebSocket Streaming

| Action | Description | Key Payload Fields | |---|---|---| | desktop_stream_start | Start a desktop frame stream | sessionId, quality, scaleFactor, maxFps | | desktop_stream_stop | Stop a desktop frame stream | sessionId | | desktop_input | Send mouse/keyboard input | sessionId, event | | desktop_config | Update streaming configuration | sessionId, quality, scaleFactor, maxFps |

`desktop_stream_start`

| Param | Type | Default | Description | |---|---|---|---| | sessionId | string | Required | Unique session identifier | | quality | int | Default config | JPEG quality 1-100 | | scaleFactor | float | Default config | Image scale factor 0.0-1.0 | | maxFps | int | Default config | Maximum frames per second 1-30 |

Returns { sessionId, screenWidth, screenHeight }.

`desktop_input`

| Param | Type | Required | Description | |---|---|---|---| | sessionId | string | Yes | Session to send input to | | event | object | Yes | Input event object (see below) |

The event object fields:

| Field | Type | Description | |---|---|---| | type | string | Required. Event type: mousemove, mousedown, mouseup, click, dblclick, keydown, keyup, scroll | | x | int | Mouse X coordinate | | y | int | Mouse Y coordinate | | button | string | Mouse button: left, right, middle | | key | string | Key name for keyboard events | | delta | int | Scroll delta | | modifiers | string[] | Modifier keys: ctrl, alt, shift, meta |

`desktop_config`

| Param | Type | Range | Description | |---|---|---|---| | sessionId | string | Required | Session to update | | quality | int | 1-100 | JPEG quality | | scaleFactor | float | 0.0-1.0 | Image scale factor | | maxFps | int | 1-30 | Maximum frames per second |

At least one of quality, scaleFactor, or maxFps must be provided.

Script Execution

Execute scripts on managed devices. Supports Bash, PowerShell, Python, and other interpreters. Both script and run_script invoke the same handler.

| Action | Description | Key Payload Fields | |---|---|---| | script / run_script | Execute a script | content, language, timeoutSeconds, runAs, parameters | | script_cancel | Cancel a running script | executionId | | script_list_running | List currently running scripts | — |

`script` / `run_script`

| Param | Type | Default | Description | |---|---|---|---| | content | string | Required | Script source code | | language | string | "bash" | Script type: bash, powershell, python, cmd, etc. | | scriptId | string | "" | Reference ID for tracking | | timeoutSeconds | int | 300 | Execution timeout (5 minutes default) | | runAs | string | "" | User context: "" (system), "user" (interactive user), or a specific username | | parameters | object | {} | Key-value map of script parameters |

`script_cancel`

| Param | Type | Required | Description | |---|---|---|---| | executionId | string | Yes | Execution ID to cancel |

`script_list_running`

No payload parameters. Returns { running: [...], count: N }.

Patching

Scan for, download, and install OS patches. Includes pre-flight checks for disk space, AC power, and maintenance windows.

| Action | Description | Key Payload Fields | |---|---|---| | patch_scan | Scan for available patches | source | | install_patches | Install pending patches | patchIds | | download_patches | Download patches without installing | patchIds | | rollback_patches | Roll back installed patches | patchIds |

`patch_scan`

| Param | Type | Default | Description | |---|---|---|---| | source | string | "" | Audit source identifier (for logging) |

Returns { pendingCount, installedCount, warning }. Also sends full patch inventory to the API as telemetry.

`install_patches`

Runs pre-flight checks (disk space, AC power, maintenance window, service health) before installation. Fails if any check does not pass.

| Param | Type | Required | Description | |---|---|---|---| | patchIds | string[] | Yes | Array of patch IDs to install |

`download_patches`

Downloads patches to local cache without installing. Runs a subset of pre-flight checks (disk space and service health, skips AC power and maintenance window).

| Param | Type | Required | Description | |---|---|---|---| | patchIds | string[] | Yes | Array of patch IDs to download |

Returns { downloadedCount, failedCount, results[] } with per-patch status. Sends progress events via WebSocket during download.

`rollback_patches`

| Param | Type | Required | Description | |---|---|---|---| | patchIds | string[] | Yes | Array of patch IDs to roll back |

Reboot Management

Schedule, cancel, and check the status of managed reboots (separate from the immediate reboot system command).

| Action | Description | Key Payload Fields | |---|---|---| | schedule_reboot | Schedule a deferred reboot | delayMinutes, reason, source, deadline | | cancel_reboot | Cancel a scheduled reboot | — | | get_reboot_status | Get current reboot schedule state | — |

`schedule_reboot`

| Param | Type | Default | Description | |---|---|---|---| | delayMinutes | int | 60 | Minutes until reboot (1-10080, i.e. up to 7 days) | | reason | string | "Scheduled by administrator" | Reboot reason for logging and user notification | | source | string | "manual" | Initiator: "manual", "patch", "policy", etc. | | deadline | string | — | Optional RFC 3339 timestamp to override calculated deadline |

`cancel_reboot`

No payload parameters. Returns { cancelled: true }.

`get_reboot_status`

No payload parameters. Returns the full RebootState object with schedule details.

Security

Collect security status, run malware/threat scans, and manage quarantined threats.

| Action | Description | Key Payload Fields | |---|---|---| | security_collect_status | Collect security posture (AV, firewall, etc.) | — | | security_scan | Run a security/malware scan | scanType, paths, scanRecordId, triggerDefender | | security_threat_quarantine | Quarantine a detected threat | path, name, threatType, severity, quarantineDir | | security_threat_remove | Permanently remove a threat | path, name, threatType, severity | | security_threat_restore | Restore a quarantined file | quarantinedPath, originalPath |

`security_collect_status`

No payload parameters. Returns the device security status including antivirus, firewall, and encryption state.

`security_scan`

| Param | Type | Default | Description | |---|---|---|---| | scanType | string | "quick" | Scan type: "quick", "full", or "custom" | | paths | string[] | — | Paths to scan (required when scanType is "custom") | | scanRecordId | string | "" | ID for tracking the scan in the dashboard | | triggerDefender | bool | false | (Windows only) Also trigger Windows Defender scan |

Returns { scanRecordId, scanType, durationMs, threatsFound, threats[], status }.

`security_threat_quarantine`

| Param | Type | Default | Description | |---|---|---|---| | path | string | Required | Path of the threat file | | name | string | "" | Threat name | | threatType | string | "malware" | Threat classification | | severity | string | "medium" | Threat severity | | quarantineDir | string | Platform default | Custom quarantine directory |

`security_threat_remove`

| Param | Type | Default | Description | |---|---|---|---| | path | string | Required | Path of the threat file to permanently delete | | name | string | "" | Threat name | | threatType | string | "malware" | Threat classification | | severity | string | "medium" | Threat severity |

`security_threat_restore`

| Param | Type | Required | Description | |---|---|---|---| | quarantinedPath | string | Yes | Path of the quarantined file | | originalPath | string | Yes | Original file path to restore to |

Network

Network discovery, SNMP polling, and connectivity checks for monitoring.

| Action | Description | Key Payload Fields | |---|---|---| | network_discovery | Discover hosts on a network | subnets, methods, portRanges, concurrency | | snmp_poll | Poll an SNMP device for metrics | target, version, community, oids | | network_ping | Ping a host (ICMP with TCP fallback) | target, count, timeout | | network_tcp_check | TCP port connectivity check | target, port, expectBanner, timeout | | network_http_check | HTTP/HTTPS endpoint check | url, method, expectedStatus, expectedBody, verifySsl | | network_dns_check | DNS record lookup check | hostname, recordType, expectedValue, nameserver |

`network_discovery`

| Param | Type | Default | Description | |---|---|---|---| | subnets | string[] | — | CIDR subnets to scan (e.g. ["192.168.1.0/24"]) | | excludeIps | string[] | — | IP addresses to skip | | methods | string[] | — | Scan methods: ping, arp, port | | portRanges | string[] | — | Port ranges for port scanning (e.g. ["22", "80", "443"]) | | snmpCommunities | string[] | — | SNMP community strings to try | | timeout | int | 2 | Per-host timeout in seconds | | concurrency | int | 128 | Max concurrent scan workers | | deepScan | bool | false | Enable deep scanning (more ports, slower) | | identifyOS | bool | false | Attempt OS fingerprinting | | resolveHostnames | bool | false | Perform reverse DNS lookups | | jobId | string | "" | Job ID for tracking |

`snmp_poll`

| Param | Type | Default | Description | |---|---|---|---| | target | string | Required | Target IP or hostname | | port | int | 161 | SNMP port | | version | string | "v2c" | SNMP version: "v1", "v2c", "v3" | | community | string | "public" | Community string (v1/v2c) | | username | string | "" | SNMPv3 username | | authProtocol | string | "" | SNMPv3 auth protocol | | authPassword | string | "" | SNMPv3 auth passphrase | | privProtocol | string | "" | SNMPv3 privacy protocol | | privPassword | string | "" | SNMPv3 privacy passphrase | | oids | string[] | — | OIDs to poll | | timeout | int | 2 | Request timeout in seconds | | retries | int | 1 | Number of retries | | deviceId | string | "" | Device ID for tracking |

`network_ping`

| Param | Type | Default | Description | |---|---|---|---| | target | string | Required | IP address or hostname | | monitorId | string | "" | Monitor ID for tracking | | timeout | int | 5 | Timeout in seconds | | count | int | 4 | Number of ping attempts |

Falls back to TCP connect (ports 443, then 80) if ICMP fails (common when running without root).

`network_tcp_check`

| Param | Type | Default | Description | |---|---|---|---| | target | string | Required | IP address or hostname | | port | int | 443 | TCP port to check | | monitorId | string | "" | Monitor ID for tracking | | timeout | int | 5 | Connection timeout in seconds | | expectBanner | string | "" | Expected string in the service banner |

Returns { status, responseMs } and optionally { banner } if expectBanner is set. Status is "degraded" if the banner does not match.

`network_http_check`

| Param | Type | Default | Description | |---|---|---|---| | url | string | Required | Full URL to check (e.g. https://example.com/health) | | method | string | "GET" | HTTP method | | monitorId | string | "" | Monitor ID for tracking | | expectedStatus | int | 200 | Expected HTTP status code | | expectedBody | string | "" | Expected string in response body | | verifySsl | bool | true | Verify TLS certificate | | followRedirects | bool | true | Follow HTTP redirects | | timeout | int | 10 | Request timeout in seconds |

Returns { status, statusCode, responseMs } plus { sslExpiry, sslDaysRemaining } for HTTPS endpoints.

`network_dns_check`

| Param | Type | Default | Description | |---|---|---|---| | hostname | string | Required | Hostname to look up | | recordType | string | "A" | Record type: A, AAAA, MX, CNAME, TXT, NS | | monitorId | string | "" | Monitor ID for tracking | | expectedValue | string | "" | Expected value in results | | nameserver | string | "" | Custom DNS server (e.g. 8.8.8.8) | | timeout | int | 5 | Lookup timeout in seconds |

Backup Management

Run, list, stop, and verify backups using the configured backup provider.

| Action | Description | Key Payload Fields | |---|---|---| | backup_run | Start a backup job | — | | backup_list | List backup snapshots | — | | backup_stop | Stop a running backup | — | | backup_verify | Verify backup integrity | verificationType | | backup_test_restore | Test-restore a snapshot | snapshotId, targetPath | | backup_cleanup | Clean up expired snapshots | — |

`backup_run`

No payload parameters. Requires backup to be configured on the agent. Returns { jobId, status, snapshotId, filesBackedUp, bytesBackedUp }.

{ "action": "backup_run", "payload": {} }

`backup_list`

No payload parameters. Returns { snapshots[], count }.

`backup_stop`

No payload parameters. Stops the currently running backup job.

`backup_verify`

| Param | Type | Default | Description | |---|---|---|---| | verificationType | string | "integrity" | integrity (checksum) or test_restore (extract to temp) |

{
  "action": "backup_verify",
  "payload": { "verificationType": "test_restore" }
}

`backup_test_restore`

| Param | Type | Required | Description | |---|---|---|---| | snapshotId | string | Yes | Snapshot to test-restore | | targetPath | string | No | Temporary restore destination |

{
  "action": "backup_test_restore",
  "payload": {
    "snapshotId": "snap-20260329-0200",
    "targetPath": "/tmp/restore-test"
  }
}

`backup_cleanup`

No payload parameters. Removes snapshots that exceed the configured retention policy.

Software Inventory

| Action | Description | Key Payload Fields | |---|---|---| | collect_software | Collect installed software inventory | — |

No payload parameters. Runs the software collector and returns the full list of installed applications with name, version, publisher, install date, and size.

File Transfer

Transfer files to/from managed devices.

| Action | Description | Key Payload Fields | |---|---|---| | file_transfer | Initiate a file transfer | direction, path, transferId | | cancel_transfer | Cancel an in-progress transfer | transferId |

`file_transfer`

Payload is passed directly to the file transfer manager. Key fields include the transfer direction and file path.

{
  "action": "file_transfer",
  "payload": {
    "direction": "download",
    "path": "/var/log/application.log",
    "transferId": "xfer-a1b2c3d4"
  }
}

`cancel_transfer`

| Param | Type | Required | Description | |---|---|---|---| | transferId | string | Yes | Transfer ID to cancel |

{
  "action": "cancel_transfer",
  "payload": { "transferId": "xfer-a1b2c3d4" }
}

User Helper Commands

These commands require the user-mode helper process to be running in a user’s session.

| Action | Description | Key Payload Fields | |---|---|---| | notify_user | Send a desktop notification | title, body, icon, urgency, username, actions | | tray_update | Update the system tray icon/menu | status, tooltip, menuItems |

`notify_user`

| Param | Type | Default | Description | |---|---|---|---| | title | string | "Breeze Agent" | Notification title | | body | string | Required | Notification body text | | icon | string | "" | Icon path or identifier | | urgency | string | "normal" | Urgency level: "low", "normal", "critical" | | username | string | "" | Target username (empty = first available session) | | actions | string[] | — | Action button labels |

`tray_update`

| Param | Type | Default | Description | |---|---|---|---| | status | string | "ok" | Tray icon status indicator | | tooltip | string | "Breeze Agent" | Tooltip text | | menuItems | array | — | Array of { id, label, enabled } menu items |

Breeze Agent Service Management

Linux (systemd)

sudo systemctl start breeze-agent
sudo systemctl stop breeze-agent
sudo systemctl restart breeze-agent
sudo systemctl status breeze-agent

# View logs
sudo journalctl -u breeze-agent -f

macOS (launchd)

sudo launchctl load /Library/LaunchDaemons/com.breeze.agent.plist
sudo launchctl unload /Library/LaunchDaemons/com.breeze.agent.plist

# View logs
sudo log show --predicate 'process == "breeze-agent"' --last 1h

Windows (Services)

Start-Service BreezeAgent
Stop-Service BreezeAgent
Restart-Service BreezeAgent
Get-Service BreezeAgent

# View logs
Get-EventLog -LogName Application -Source BreezeAgent -Newest 50

Command Timeouts

The API runs a stale command reaper every 2 minutes that cleans up commands stuck in pending or sent status. Each command type has a timeout tier that determines how long the system waits before marking it as failed:

| Tier | Duration | Command types | |------|----------|---------------| | Short | 5 min | Process management, service management, event logs, scheduled tasks, registry, file operations, screenshots, computer actions, security status collection | | Medium | 30 min | Security scans, patch scans, software uninstall, filesystem analysis, safe mode reboot, self-uninstall, evidence collection, containment actions, reliability metrics, CIS remediation | | Long | 2 hours | Patch installation, backup verify/test-restore/cleanup, CIS benchmarks, sensitive data scans, file encryption/secure delete/quarantine | | Excluded | Never reaped | Terminal sessions (terminal_start, terminal_data, terminal_resize, terminal_stop) |

Script commands use the script’s own timeoutSeconds value (default 300s) plus a 5-minute grace buffer, so the server timeout is always slightly longer than the agent-side timeout.

When a command times out, it is marked failed with timedOutBy: 'server' in the error message.

Heartbeat Telemetry

The agent sends a heartbeat every 60 seconds containing:

| Field | Description | |---|---| | cpu | CPU usage percentage | | memory | Memory usage (used/total) | | disk | Disk usage per mount point | | network | Network interface stats | | uptime | System uptime | | os | OS name and version | | hostname | Current hostname | | agentVersion | Running agent version |

User-Mode Helper

The agent includes a user-mode helper process for operations that require user-session context:

Desktop notifications (notify_user)
User-specific inventory (installed apps, browser extensions)
Session-aware remote desktop
Script execution as a specific user (runAs)
System tray icon updates (tray_update)

Install the user helper:

Linux
macOS

sudo make install-user-helper
systemctl --user enable breeze-agent-user

sudo make install-user-helper
# LaunchAgent auto-starts at login

Commands & Config

Command Flow

Command Result Format

Process Management

list_processes

get_process

kill_process

Service Management

list_services

get_service / start_service / stop_service / restart_service

Event Logs (Windows)

event_logs_query

event_log_get

Scheduled Tasks (Windows)

tasks_list

task_get / task_run / task_enable / task_disable

task_history

Registry (Windows)

Common Parameters

registry_get

registry_set

registry_delete

System

reboot / shutdown

lock

reboot_safe_mode

set_auto_update

refresh_inventory

File Operations

file_list

file_read

file_write

file_delete

file_mkdir

file_rename

filesystem_analysis

Terminal

terminal_start

terminal_data

terminal_resize

terminal_stop