System Tools

System Tools provide a suite of remote administration capabilities that let technicians inspect and manage managed devices directly from the Breeze dashboard. You access System Tools from a device’s detail page by opening the Remote Tools panel, which organizes all tools into a tabbed interface.

Every operation is dispatched to the Breeze agent running on the target device via the command queue. All mutating actions (killing processes, starting/stopping services, editing the registry, uploading files, running/enabling/disabling scheduled tasks) are recorded in the audit log.

Note

System Tools require authentication with MFA and a role that includes the devices.read permission for read operations or devices.execute for mutating operations.

---

Accessing Remote Tools

1. Navigate to the device. Open the device detail page from the Devices list or by clicking a device name anywhere in the dashboard.

2. Open Remote Tools. Click the Remote Tools button on the device page. The Remote Tools panel opens showing the device name, OS type, and a row of tool tabs.

3. Select a tool tab. Click any tab to switch between tools:

   • Processes — available on all platforms
   • Services — Windows only
   • Registry — Windows only
   • Event Log — Windows only
   • Scheduled Tasks — Windows only
   • Terminal — available on all platforms
   • File Browser — available on all platforms

   On macOS and Linux devices, Windows-only tabs are automatically hidden.

---

Using the File Browser

The File Browser tab lets you navigate the device’s filesystem, download files, and upload files. It works on all platforms (Windows, macOS, Linux).

• Navigate directories. The browser opens to a default path based on the OS. Click folder names to navigate into them. Use the breadcrumb path at the top to jump back to parent directories.
• View file details. Each entry shows the file or directory name, size, last modified date, and permissions.
• Download files. Select a file and click the download button. The file is transferred from the device and downloaded to your browser.
• Upload files. Click the upload button to send a file to the device at the current path. You can upload text or binary files.

File Browser API reference

For scripted file operations, the File Browser API is documented below.

Listing a directory

Send a GET request with the absolute path you want to browse. The agent returns an array of entries, each describing a file or directory at that path.

GET /api/v1/system-tools/devices/:deviceId/files?path=/var/log

Each entry in the response includes:

Field	Type	Description
name	string	File or directory name
path	string	Full path on the device
type	string	"file" or "directory"
size	number	Size in bytes (files only)
modified	string	ISO 8601 last-modified timestamp
permissions	string	POSIX permission string (e.g. rwxr-xr-x)

Downloading a file

GET /api/v1/system-tools/devices/:deviceId/files/download?path=/tmp/example.txt

The agent reads the file, base64-encodes it, and returns it to the API. The API decodes it and streams the raw bytes back to the caller with Content-Disposition: attachment and Content-Type: application/octet-stream headers. The filename is derived from the remote path.

Uploading a file

POST /api/v1/system-tools/devices/:deviceId/files/upload
Content-Type: application/json

{
  "path": "/tmp/config.yaml",
  "content": "server:\n  port: 8080\n",
  "encoding": "text"
}

Body Field	Type	Required	Description
path	string	Yes	Absolute destination path on the device
content	string	Yes	File content (plain text or base64)
encoding	string	No	"text" (default) or "base64"

File uploads are audit-logged with the destination path, encoding, and size.

---

Using the Process Manager

The Processes tab displays all running processes on the device, sorted by CPU usage by default. Use this tool to identify resource-heavy processes and terminate misbehaving ones.

• View processes. The process list shows PID, name, CPU usage, memory usage, owning user, and status for each process. Click a process row to view additional details including command line, thread count, and parent PID.
• Search and filter. Use the search bar to filter by process name, user, command line, or PID.
• Kill a process. Click the kill button next to a process to terminate it. A confirmation is required. Force-kill sends SIGKILL (or the Windows equivalent) instead of a graceful SIGTERM.
• Refresh. Click the refresh button to reload the process list from the device.

The Process Manager works on all platforms (Windows, macOS, Linux).

Process Manager API reference

Listing processes

GET /api/v1/system-tools/devices/:deviceId/processes?page=1&limit=50&search=node

Query Parameter	Type	Default	Description
page	number	1	Page number
limit	number	50	Results per page (max 500)
search	string	—	Filter by name, user, command line, or PID

The agent sorts results by CPU usage (descending) by default and supports sorting by pid, name, user, memory, or cpu.

Each process entry includes:

Field	Type	Description
pid	number	Process ID
name	string	Process name
cpuPercent	number	Current CPU usage percentage
memoryMb	number	Resident memory in MB
user	string	Owning user
status	string	running, sleeping, stopped, or zombie
commandLine	string	Full command line
parentPid	number	Parent process ID
threads	number	Thread count

Getting process details

GET /api/v1/system-tools/devices/:deviceId/processes/2048

Returns the same fields as the list, but for a single process identified by PID.

Killing a process

POST /api/v1/system-tools/devices/:deviceId/processes/3456/kill?force=true

Query Parameter	Type	Default	Description
force	boolean	false	When true, sends SIGKILL instead of SIGTERM (or the Windows equivalent)

This action is audit-logged with the PID, force flag, and result.

---

Using the Service Manager

The Services tab lists all system services with their current status. Use it to start, stop, or restart services without opening a remote session.

• View services. Each service shows its name, display name, status (Running, Stopped, Paused, Starting, Stopping), startup type (Automatic, Manual, Disabled), and service account.
• Search and filter. Search by service name and filter by status (e.g., show only running services or only stopped services).
• Start, stop, or restart. Click the corresponding action button next to a service. The action is sent to the agent and the service list refreshes automatically.
• Agent service detection. If you restart the Breeze agent service itself, the UI displays a “Agent Restarting” banner and automatically polls until the agent reconnects.

Note

The Services tab appears only on Windows devices in the Remote Tools panel. On Linux and macOS, service management is available through the Terminal tab using systemctl or launchctl.

Service Manager API reference

The Service Manager has platform-specific implementations:

• Windows: Uses the Windows Service Control Manager API
• Linux: Uses systemctl (systemd)
• macOS: Uses launchctl (launchd)

Listing services

GET /api/v1/system-tools/devices/:deviceId/services?page=1&limit=50&search=WinRM&status=running

Query Parameter	Type	Default	Description
page	number	1	Page number
limit	number	50	Results per page (max 500)
search	string	—	Filter by service name
status	string	—	Filter by status (e.g. running, stopped)

The API normalizes service data from each platform into a consistent shape:

Field	Type	Description
name	string	Service identifier (e.g. WinRM, sshd)
displayName	string	Human-readable name
status	string	running, stopped, paused, starting, or stopping
startType	string	auto, manual, disabled, or auto_delayed
account	string	Service account (e.g. LocalSystem)
description	string	Service description text
path	string	Executable path
dependencies	string[]	Names of services this service depends on

Getting service details

GET /api/v1/system-tools/devices/:deviceId/services/WinRM

Starting, stopping, and restarting a service

POST /api/v1/system-tools/devices/:deviceId/services/WinRM/start
POST /api/v1/system-tools/devices/:deviceId/services/WinRM/stop
POST /api/v1/system-tools/devices/:deviceId/services/WinRM/restart

All three actions are audit-logged with the service name and result.

---

Using the Registry Editor

The Registry tab provides a tree-based browser for the Windows registry. Use it to inspect configuration settings, modify values, and create or delete keys — all without opening a remote desktop session.

• Navigate hives and keys. The left panel shows a tree structure starting from the supported hives (HKEY_LOCAL_MACHINE, HKEY_CURRENT_USER, HKEY_CLASSES_ROOT, HKEY_USERS, HKEY_CURRENT_CONFIG). Click a key to expand its subkeys. The right panel displays the values at the selected key.
• View values. Each value shows its name, type (REG_SZ, REG_DWORD, REG_QWORD, REG_MULTI_SZ, REG_EXPAND_SZ, REG_BINARY), and data.
• Edit values. Click a value to open the edit dialog. Modify the data and save.
• Create and delete. Create new keys or values using the corresponding buttons. Delete keys or values with the delete action.

Caution

The Registry Editor is Windows-only. It only appears on Windows devices in the Remote Tools panel.

Danger

Registry modifications can make a Windows system unbootable. All write and delete operations are audit-logged.

Registry Editor API reference

The Registry Editor provides full read and write access to the Windows registry via API.

Supported hives

The following registry hives are accepted by all registry endpoints:

• HKEY_LOCAL_MACHINE
• HKEY_CURRENT_USER
• HKEY_CLASSES_ROOT
• HKEY_USERS
• HKEY_CURRENT_CONFIG

Listing subkeys

GET /api/v1/system-tools/devices/:deviceId/registry/keys?hive=HKEY_LOCAL_MACHINE&path=SOFTWARE

Each key entry includes:

Field	Type	Description
name	string	Key name
path	string	Full registry path
subKeyCount	number	Number of child keys
valueCount	number	Number of values in this key
lastModified	string	Last modification timestamp

Listing values at a key

GET /api/v1/system-tools/devices/:deviceId/registry/values?hive=HKEY_LOCAL_MACHINE&path=SOFTWARE

Each value entry includes:

Field	Type	Description
name	string	Value name ((Default) for the default value)
type	string	One of the supported types (see below)
data	string, number, string[], number[]	Parsed value data

Supported value types

Type	API data format
REG_SZ	string
REG_EXPAND_SZ	string
REG_DWORD	number
REG_QWORD	number
REG_MULTI_SZ	string[]
REG_BINARY	number[] (byte values 0-255)

The API normalizes raw agent responses automatically. For example, REG_DWORD values returned as strings are parsed to numbers, and REG_BINARY hex strings (e.g. "00 01 0A FF") are converted to byte arrays (e.g. [0, 1, 10, 255]).

Reading a specific value

GET /api/v1/system-tools/devices/:deviceId/registry/value?hive=HKEY_LOCAL_MACHINE&path=SOFTWARE&name=ProductName

The response includes a fullPath field combining the hive, path, and value name.

Setting a value

PUT /api/v1/system-tools/devices/:deviceId/registry/value
Content-Type: application/json

{
  "hive": "HKEY_LOCAL_MACHINE",
  "path": "SOFTWARE\\Breeze",
  "name": "Version",
  "type": "REG_SZ",
  "data": "1.0.0"
}

Deleting a value

DELETE /api/v1/system-tools/devices/:deviceId/registry/value?hive=HKEY_LOCAL_MACHINE&path=SOFTWARE&name=TestValue

Creating a key

POST /api/v1/system-tools/devices/:deviceId/registry/key
Content-Type: application/json

{
  "hive": "HKEY_LOCAL_MACHINE",
  "path": "SOFTWARE\\Breeze"
}

Deleting a key

DELETE /api/v1/system-tools/devices/:deviceId/registry/key?hive=HKEY_LOCAL_MACHINE&path=SOFTWARE\\Breeze

Danger

Registry modifications can make a Windows system unbootable. All registry write and delete operations are audit-logged, including the hive, path, value name, type, and data.

---

Using Event Logs

The Event Log tab lets you query the Windows Event Log system directly from the dashboard. Use it to investigate errors, audit security events, and troubleshoot service failures.

• Select a log. The left panel lists all available event logs (System, Application, Security, etc.) with their record count and last write time. Click a log to select it.
• Filter events. Use the filter controls to narrow results by severity level (Information, Warning, Error, Critical), source, event ID, and date range.
• Browse results. Events are displayed in a table with timestamp, level, source, event ID, and message. Severity levels are color-coded for quick scanning.
• View event details. Click an event to see its full details including the raw XML data.

Caution

Event Logs are Windows-only. This tab only appears on Windows devices in the Remote Tools panel.

Event Logs API reference

The Event Logs API queries the Windows Event Log system programmatically.

Listing available logs

GET /api/v1/system-tools/devices/:deviceId/eventlogs

Each log entry includes:

Field	Type	Description
name	string	Log name (e.g. System)
displayName	string	Human-readable name
recordCount	number	Total number of records
maxSize	number	Maximum log size in bytes
retentionDays	number	Retention policy in days
lastWriteTime	string	ISO 8601 timestamp of last write

Getting log info

GET /api/v1/system-tools/devices/:deviceId/eventlogs/System

Returns the metadata for a single log by name.

Querying events

GET /api/v1/system-tools/devices/:deviceId/eventlogs/System/events?level=error&source=Service+Control+Manager&page=1&limit=50

Query Parameter	Type	Default	Description
page	number	1	Page number
limit	number	50	Results per page (max 500)
level	string	—	information, warning, error, critical, or verbose
source	string	—	Filter by event source
eventId	number	—	Filter by Windows event ID
startTime	string	—	ISO 8601 start time
endTime	string	—	ISO 8601 end time

Each event entry includes:

Field	Type	Description
recordId	number	Unique record identifier
timeCreated	string	ISO 8601 timestamp
level	string	Normalized: information, warning, error, critical, or verbose
source	string	Event source (e.g. Kernel-General)
eventId	number	Windows event ID
message	string	Event message text
category	string	Event category
user	string/null	SID of the user (e.g. S-1-5-18)
computer	string	Computer name

Getting a specific event

GET /api/v1/system-tools/devices/:deviceId/eventlogs/System/events/15234

Returns full details for a single event by record ID, including the optional rawXml field with the original Windows event XML.

---

Using Scheduled Tasks

The Scheduled Tasks tab provides a view of the Windows Task Scheduler. Use it to inspect scheduled jobs, trigger them on demand, and enable or disable tasks.

• Browse tasks. Tasks are displayed in a searchable, paginated list with name, status (Ready, Running, Disabled, Queued), last run time, last result, and next run time. Browse by folder to navigate the Task Scheduler folder hierarchy.
• View task details. Click a task to open its detail panel showing triggers (daily, weekly, boot, logon, etc.), actions (executables, arguments), conditions, and settings.
• Run a task. Click the Run button to trigger immediate execution.
• Enable or disable. Toggle a task between enabled and disabled states.
• View task history. Open the history panel for a task to see past executions with timestamps, event IDs, status levels (info, warning, error), and result codes.

Caution

Scheduled Tasks are Windows-only. This tab only appears on Windows devices in the Remote Tools panel.

Scheduled Tasks API reference

The Scheduled Tasks API provides programmatic access to Windows Task Scheduler.

Listing tasks

GET /api/v1/system-tools/devices/:deviceId/tasks?page=1&limit=50&folder=\Microsoft\Windows&search=Defender

Query Parameter	Type	Default	Description
page	number	1	Page number
limit	number	50	Results per page (max 500)
folder	string	\	Task scheduler folder to browse
search	string	—	Filter by task name

Each task entry includes:

Field	Type	Description
path	string	Full task path (e.g. \Microsoft\Windows\...)
name	string	Task name
state	string	ready, running, disabled, queued, or unknown
lastRunTime	string/null	ISO 8601 timestamp of last execution
lastRunResult	number/null	Exit code from last run
nextRunTime	string/null	ISO 8601 timestamp of next scheduled execution
author	string	Task author
description	string	Task description
triggers	array	Trigger definitions with type, enabled, and optional schedule
actions	array	Action definitions with type, optional path and arguments

Getting task details

The task path must be URL-encoded in the path parameter:

GET /api/v1/system-tools/devices/:deviceId/tasks/%5CMicrosoft%5CWindows%5CWindows%20Defender%5CWindows%20Defender%20Scheduled%20Scan

Running a task

POST /api/v1/system-tools/devices/:deviceId/tasks/:encodedPath/run

Triggers an immediate execution of the task. Audit-logged.

Enabling a task

POST /api/v1/system-tools/devices/:deviceId/tasks/:encodedPath/enable

Enables a previously disabled task. Audit-logged.

Disabling a task

POST /api/v1/system-tools/devices/:deviceId/tasks/:encodedPath/disable

Disables a task so it no longer runs on schedule. Audit-logged.

Viewing task history

GET /api/v1/system-tools/devices/:deviceId/tasks/:encodedPath/history?limit=10

Query Parameter	Type	Default	Description
limit	number	50	Number of history entries (max 200)

Each history entry includes:

Field	Type	Description
id	string	History entry ID
eventId	number	Task Scheduler event ID
timestamp	string	ISO 8601 timestamp
level	string	info, warning, or error
message	string	Descriptive message
resultCode	number	Exit code (present when available)

---

API Reference (For Integrators)

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

File Browser

Method	Path	Description	Permission
GET	/files?path=...	List directory	devices.read
GET	/files/download?path=...	Download file	devices.read
POST	/files/upload	Upload file	devices.execute

Process Manager

Method	Path	Description	Permission
GET	/processes	List processes	devices.read
GET	/processes/:pid	Get process details	devices.read
POST	/processes/:pid/kill	Kill process	devices.execute

Service Manager

Method	Path	Description	Permission
GET	/services	List services	devices.read
GET	/services/:name	Get service details	devices.read
POST	/services/:name/start	Start service	devices.execute
POST	/services/:name/stop	Stop service	devices.execute
POST	/services/:name/restart	Restart service	devices.execute

Registry Editor (Windows only)

Method	Path	Description	Permission
GET	/registry/keys?hive=...&path=...	List subkeys	devices.read
GET	/registry/values?hive=...&path=...	List values	devices.read
GET	/registry/value?hive=...&path=...&name=...	Get value	devices.read
PUT	/registry/value	Set value	devices.execute
DELETE	/registry/value?hive=...&path=...&name=...	Delete value	devices.execute
POST	/registry/key	Create key	devices.execute
DELETE	/registry/key?hive=...&path=...	Delete key	devices.execute

Event Logs (Windows only)

Method	Path	Description	Permission
GET	/eventlogs	List logs	devices.read
GET	/eventlogs/:name	Get log info	devices.read
GET	/eventlogs/:name/events	Query events	devices.read
GET	/eventlogs/:name/events/:recordId	Get event detail	devices.read

Scheduled Tasks (Windows only)

Method	Path	Description	Permission
GET	/tasks	List tasks	devices.read
GET	/tasks/:path	Get task details	devices.read
GET	/tasks/:path/history	Get task history	devices.read
POST	/tasks/:path/run	Run task	devices.execute
POST	/tasks/:path/enable	Enable task	devices.execute
POST	/tasks/:path/disable	Disable task	devices.execute

---

Troubleshooting

Device not found or access denied (404)

Every System Tools request verifies that the device exists and that the authenticated user’s organization has access to it. If you receive a 404, confirm that:

• The device UUID is correct.
• Your user account has access to the organization that owns the device.
• The device has been enrolled (not deleted).

Agent failed / device may be offline (502)

System Tools commands are dispatched to the agent via the command queue with a 30-second timeout (15 seconds for process kill). A 502 or 500 response with a message like “Failed to get processes” or “Agent failed to list files” indicates:

• The device agent is offline or unreachable.
• The agent did not respond within the timeout window.
• The agent encountered an internal error executing the command.

Check the device’s online status on its detail page before retrying.

”Failed to parse agent response” (502)

This means the agent returned a response that the API could not parse as valid JSON. This can happen if:

• The agent version is outdated and returns a different payload format.
• The command produced unexpected output (e.g., a system error message instead of JSON).

Update the agent to the latest version and retry.

”Registry is only supported on Windows” / “Event logs are only supported on Windows” / “Scheduled tasks are only supported on Windows”

These tools require a Windows device. The agent returns a platform-not-supported error on macOS and Linux. Process management, service management, and the file browser work on all platforms.

Permission denied on service start/stop

On Linux, the agent must be running with sufficient privileges (typically root) to manage systemd services. On macOS, managing system-level launchd services similarly requires elevated privileges. On Windows, the agent service account must have permission to control the target service.

Registry write operations failing

Ensure the agent is running with sufficient privileges to write to the target registry hive. Writing to HKEY_LOCAL_MACHINE typically requires the agent to run as SYSTEM or an administrator. The path must not exceed 1024 characters and the value name must not exceed 256 characters (enforced by input validation).