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)

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 breeze-agent
Stop-Service breeze-agent
Restart-Service breeze-agent
Get-Service breeze-agent

# View logs
Get-EventLog -LogName Application -Source breeze-agent -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

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

Remote Desktop

WebRTC (Legacy)

start_desktop