Commands & Config

Command Execution

The API sends commands to agents over WebSocket. Each command has an action and optional payload:

Action	Description	Payload
run_script	Execute a script	{ scriptId, args?, timeout? }
collect_inventory	Gather full system inventory	—
discovery_scan	Run network discovery	{ subnet, scanType }
restart_service	Restart a system service	{ serviceName }
file_transfer	Initiate file transfer	{ direction, path }
upgrade_agent	Self-upgrade to new version	{ version, downloadUrl }
terminal_start	Open a remote terminal session	—
terminal_input	Send input to terminal	{ data }
terminal_resize	Resize terminal	{ cols, rows }

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.

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

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
• User-specific inventory (installed apps, browser extensions)
• Session-aware remote desktop

Install the user helper:

# Linux
sudo make install-user-helper
systemctl --user enable breeze-agent-user

# macOS
sudo make install-user-helper
# LaunchAgent auto-starts at login