Agent Diagnostics & Service Commands

Two features help you manage and diagnose the Breeze agent itself:

• Agent Diagnostic Logs — structured internal logs emitted by the agent process and shipped to the server on a schedule
• Agent Service Commands — CLI commands for registering and managing the Breeze agent as a Windows system service

---

Agent Diagnostic Logs

Agent Diagnostic Logs are structured internal logs emitted by the Breeze agent process and shipped to the Breeze server on a regular schedule. They give you visibility into what the agent is doing, warn you about issues before they become failures, and let you diagnose connectivity or update problems without needing shell access to the device.

Note

These are agent-internal operational logs. They are not OS event logs, Windows Event Viewer entries, or syslog output — those are available separately under the Event Log tab on the device detail page.

What is logged

The agent emits structured log entries with the following fields:

Field	Description
timestamp	When the event occurred (UTC)
level	Severity: debug, info, warn, error
component	Which part of the agent produced the log: heartbeat, websocket, main, updater
message	Human-readable description of the event
fields	Additional structured context as a JSON object (e.g., error details, counts, durations)
agent_version	The agent version that produced the entry

Log levels:

Level	When to expect it
debug	Verbose trace information, only emitted in debug mode
info	Normal operation milestones (heartbeat sent, WS connected, update completed)
warn	Recoverable issues the agent handled (reconnection, config reload, missed window)
error	Failures requiring attention (WS dropped, update failed, command execution error)

Components:

The primary components are:

Component	What it covers
heartbeat	Periodic check-in messages, metric collection timing
websocket	WebSocket connection lifecycle, reconnection events
main	Agent startup, shutdown, configuration loading
updater	Agent self-update process, version checks, download status

Additional components log events from subsystems such as terminal, executor, patching, filetransfer, mgmtdetect, mtls, config, health, and others. Use the component query parameter to filter for any specific subsystem.

The agent buffers logs internally and ships them in gzip-compressed batches every 60 seconds (or when the buffer reaches 500 entries) via POST /agents/:id/logs.

Note

The agent normalizes log levels to lowercase (e.g., info, warn) before shipping. The API ingestion endpoint expects lowercase values.

Note

A dedicated Diagnostic Logs UI is not yet available in the web app. Logs are accessible via the API.

Filtering and searching

The GET /devices/:id/diagnostic-logs endpoint supports several filters you can combine:

Parameter	Description
level	Comma-separated levels to include (e.g. warn,error)
component	Filter to a single component (e.g. heartbeat)
since / until	ISO 8601 timestamps to restrict to a time range
search	Full-text keyword match across the message field
page / limit	Pagination (max 1,000 per page)

All filters are additive — a log entry must match all active filters to appear.

Log retention

Diagnostic logs are retained for 7 days by default. A cleanup job runs once per day at a fixed scheduled time (not tied to server startup) and removes entries older than the retention window.

To change the retention period, set the AGENT_LOG_RETENTION_DAYS environment variable on the API server:

AGENT_LOG_RETENTION_DAYS=30

Adjusting the shipping level at runtime

By default, the agent only ships warn and error logs to conserve bandwidth. You can temporarily lower the shipping level to capture info or debug logs without restarting the agent or redeploying configuration.

Send the set_log_level command to the device:

{
  "action": "set_log_level",
  "payload": {
    "level": "debug",
    "durationMinutes": 30
  }
}

Parameter	Type	Default	Description
level	string	Required	New shipping level: debug, info, warn, or error
durationMinutes	int	60	Minutes before the level automatically reverts to warn. Set to 0 to keep the new level until the agent restarts.

After the specified duration, the agent automatically reverts to warn. This prevents accidentally leaving verbose logging enabled and filling storage with debug data.

Tip

Use this when diagnosing a connectivity or update issue on a specific device. Lower the level to debug, reproduce the problem, then query the diagnostic logs API filtered to the time window. The level reverts on its own – no cleanup step needed.

API reference

Method	Path	Description
GET	/devices/:id/diagnostic-logs	Query shipped agent logs for a device
POST	/agents/:id/logs	(Agent only) Submit a gzip-compressed log batch

Query parameters for GET /devices/:id/diagnostic-logs:

Parameter	Type	Description
level	string	Comma-separated levels: debug, info, warn, error
component	string	Filter to a single component: heartbeat, websocket, main, updater
since	ISO 8601	Include only logs at or after this datetime
until	ISO 8601	Include only logs at or before this datetime
search	string	Full-text search on the message field (case-insensitive)
page	number	Page number (1-based)
limit	number	Results per page (max 1,000)

Example — get the last 100 error logs from the websocket component:

GET /api/v1/devices/DEVICE_ID/diagnostic-logs?level=error&component=websocket&limit=100

---

Agent Service Commands

The Breeze agent binary includes a service subcommand for managing itself as a system service. These commands are run directly on the endpoint, not via the Breeze API, and are available on Windows, macOS, and Linux — each platform registers with its own native service manager (the Windows Service Control Manager, launchd on macOS, systemd on Linux) under the covers, but the install/uninstall/start/stop subcommands are the same everywhere.

Note

Elevated privileges required. On Windows, run the command from an Administrator command prompt or PowerShell session. On macOS and Linux, prefix the command with sudo.

macOS and Linux also expose a service status subcommand (sudo breeze-agent service status), which prints the native service manager’s status output. This subcommand does not exist on Windows.

Note

The examples below use Windows syntax (breeze-agent.exe, run from an Administrator prompt). On macOS and Linux, drop the .exe and prefix each command with sudo — for example sudo breeze-agent service install. The specific restart-backoff timings and Service Control Manager (SCM) details below are Windows-specific; macOS (launchd) and Linux (systemd) restart the agent automatically on failure using their own native restart policies.

Commands

Install

breeze-agent.exe service install

Registers the agent as a Windows service named BreezeAgent with the display name “Breeze RMM Agent”. The service is configured to:

• Start automatically when Windows boots
• Restart automatically on failure (after 5 s on the first failure, 10 s on the second, 30 s on the third)
• Reset the failure count after 24 hours of stable operation

Safe to re-run on a host where the service already exists: it stops the running service, replaces the binary, repoints the registration at it, and then starts the service again if it was running beforehand or the host is already enrolled. A fresh, un-enrolled host is left stopped deliberately — enroll first, then start. If the service is meant to come back and fails to start, the command exits non-zero and says so rather than reporting success.

Caution

v0.110.0 and earlier: service install did not start the service, and re-running it on a host that already had the service failed with “service already exists”. After installing or upgrading on those versions, run breeze-agent.exe service start yourself.

Uninstall

breeze-agent.exe service uninstall

Stops the service if it is running (waits up to 15 seconds), then removes it from the SCM. The agent binary itself is not deleted.

Start

breeze-agent.exe service start

Starts the BreezeAgent service via the SCM. Equivalent to sc start BreezeAgent or Start-Service BreezeAgent.

Stop

breeze-agent.exe service stop

Sends a stop signal to the BreezeAgent service via the SCM. Equivalent to sc stop BreezeAgent or Stop-Service BreezeAgent.

Typical workflows

Install and start:

# Run as Administrator
breeze-agent.exe service install
breeze-agent.exe service start

service install already starts the service on an enrolled host, so the explicit service start is only needed on a fresh host that has not enrolled yet (and on agents at v0.110.0 or earlier, where install never started anything).

Stop and uninstall:

# Run as Administrator
breeze-agent.exe service stop
breeze-agent.exe service uninstall

---

Troubleshooting

No diagnostic logs appearing

The agent must be running a version that supports log shipping. Check the agent version shown on the device detail page. If the agent is outdated, update it via Devices → Select Device → Update Agent.

Log level missing (e.g., no info or debug logs)

The agent’s log_shipping_level controls what gets shipped. The default level is warn, so info and debug logs are not shipped unless the level is explicitly lowered. Use the set_log_level WebSocket command to temporarily lower the level — the change auto-reverts to warn after 60 minutes by default.

Logs stop appearing after a certain date

Confirm the agent is still online and check AGENT_LOG_RETENTION_DAYS. If the retention window was recently shortened, older logs may have already been removed by the daily cleanup job.

service install fails with “Access is denied”

The command must be run from an Administrator command prompt or PowerShell session. Right-click the terminal and choose “Run as administrator”, then re-run the command.

service install fails with “service already exists”

Only on v0.110.0 and earlier, where service install could not upgrade an existing registration. Run breeze-agent.exe service uninstall first if you need to re-install, or breeze-agent.exe service start if the service is simply stopped. Newer agents upgrade the existing service in place instead of failing.

service start fails after install

The SCM stores the absolute path to the binary. On current agents, re-running breeze-agent.exe service install repoints the registration at the binary’s real location; on v0.110.0 and earlier you have to uninstall and reinstall the service instead. If the start still fails, check Event Viewer → Windows Logs → Application for the service’s own start error.