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.
List, inspect, start, stop, and restart system services. Platform-aware: uses systemd on Linux, launchd on macOS, and the Windows Service Control Manager.
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.
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).
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.
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).
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.
Open interactive remote terminal (PTY) sessions. Terminal commands use the term- prefix for command IDs and bypass the database queue for low-latency communication.
The original script command’s id (device_commands.id), not the script_executions row id. The agent keys its in-memory running-script map on the command id, so sending the execution row id here is a silent no-op against the deployed fleet.
scriptExecutionId
string
No
The script_executions row id, sent alongside executionId for server-side bookkeeping. Older agents (pre-#3525) ignore this field.
graceSeconds
int
No
Grace period before escalating to a hard kill. 0-30, default 5. Ignored entirely on Windows — see below.
Result (always a SUCCESS result, even when the process was not stopped):
cancelled is true only for outcome: "terminated" — the server only ever marks script_executions.status = 'cancelled' on this proof. not_found most often means the script had already finished and its result is in flight, not that the stop succeeded; kill_failed means the device tried and could not kill the process.
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.
patch_job (patch installs) or maintenance_window (maintenance sweeps) are the values Breeze itself sends
Defaults to "manual". Echoed back on the heartbeat as rebootStatus.source, so a value outside ^[a-z0-9_]{1,32}$ is dropped by the server rather than stored
deadline
string (RFC 3339)
No
must parse as RFC 3339
Defaults to now + delayMinutes. A non-empty but malformed value fails the command rather than falling back
allowDeferral
bool
No
true / false
Absent means OFF. A restart is never postponable unless this key is explicitly true
maxDeferrals
int
Only when allowDeferral is true
1-10
Ignored when allowDeferral is absent or false. When allowDeferral is true, an absent or out-of-range value fails the command
deferralMinutes
int
Only when allowDeferral is true
5-1440
Same as maxDeferrals: ignored unless allowDeferral is true, and an absent or out-of-range value then fails the command
Supported on Windows, Linux and macOS. The agent warns the logged-in user
immediately when the reboot is scheduled, follows up with reminders at 60, 15 and
5 minutes before (only where those land far enough apart to be worth sending),
and fires a final critical notice one minute out — which is also when the OS
shutdown countdown starts, so the countdown the user sees is the one the OS
honours. Every delay produces at least one warning, including delays shorter than
any reminder threshold.
For post-patch reboots the API does not choose the delay itself: it resolves
rebootDelayMinutes from the device’s effective patch Configuration Policy
(default 15 minutes, range 1-1440), and the maintenance-window reboot path reads
the same setting.
The deferral fields come from the same policy (rebootAllowDeferral,
rebootMaxDeferrals, rebootDeferralMinutes) and are resolved once, when the
restart is scheduled – editing the policy mid-countdown does not shrink a user’s
remaining postponements. They are off by default, and an agent that predates
them ignores them, so the restart behaves exactly as it always has. A restart
issued inside a maintenance window has its deadline capped at the close of that
window.
No payload parameters. Returns { cancelled: true }.
Cancellation always stops the agent’s own timers. If the OS shutdown countdown
has already started (the final minute), the agent also aborts it where the
platform allows — shutdown /a on Windows, shutdown -c on Linux. macOS cannot:
BSD shutdown(8) has no cancel flag, so the call reports the failure rather than
claiming a cancellation that did not happen.
No payload parameters. Returns the full RebootState object with schedule
details, including notificationsPlanned — how many user warnings the current
schedule will emit.
No payload parameters. Runs the software collector and returns the full list of installed applications with name, version, publisher, install date, and size.
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
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.
rebootStatus is a three-way field, not a plain optional – its meaning changes
between “the key is missing,” “the key is null,” and “the key holds an
object”:
Absent from the heartbeat body – “no news.” An agent built before this
field existed omits rebootStatus entirely, and the server leaves the
device’s stored reboot columns untouched.
rebootStatus: null – there is no restart scheduled: it was cancelled,
or it already fired. The server clears the stored columns.
rebootStatus: { ... } – the live schedule:
Field
Type
Required
Description
scheduledAt
string (RFC 3339, with offset)
Yes
When the restart will fire. The only required member – a malformed value makes the server drop the whole rebootStatus object (treated the same as absent) rather than reject the heartbeat
deadline
string (RFC 3339, with offset)
No
Absolute cutoff past which the restart happens regardless of remaining deferral budget
source
string
No
What requested the restart, echoed back from the schedule_reboot command that scheduled it: patch_job, maintenance_window, or the agent’s own manual default
deferralsUsed
int (0-10)
No
How many times the signed-in user has postponed this restart
