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.

Accessing Remote Tools

Navigate to the device. Open the device detail page from the Devices list or by clicking a device name anywhere in the dashboard.
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.
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.

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.

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

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.

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.

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).