Skip to content
Breeze RMM

Agent Installation

The Breeze agent is a single Go binary (~8 MB) with no runtime dependencies. It runs as a system service and communicates with your Breeze server over HTTPS/WSS.

Supported Platforms

Section titled “Supported Platforms”
PlatformArchitectureBinary
Linuxamd64breeze-agent-linux-amd64
Linuxarm64breeze-agent-linux-arm64
macOSamd64 (Intel)breeze-agent-darwin-amd64
macOSarm64 (Apple Silicon)breeze-agent-darwin-arm64
Windowsamd64breeze-agent-windows-amd64.exe

Quick Install

Section titled “Quick Install”
Terminal window
# Download the agent
curl -fsSL -o breeze-agent \
  https://breeze.yourdomain.com/api/v1/agents/download/linux/amd64
chmod +x breeze-agent


# Enroll and install as a service
sudo ./breeze-agent enroll YOUR_ENROLLMENT_KEY \
  --server https://breeze.yourdomain.com \
  --enrollment-secret YOUR_ENROLLMENT_SECRET


sudo ./breeze-agent service install

Pre-Configured Installers

Section titled “Pre-Configured Installers”

Instead of running manual enrollment commands, you can download a ready-to-run installer from the Breeze dashboard.

  1. Open the Add Device dialog from the Devices page.
  2. Select Download Installer and choose Windows MSI or macOS PKG.
  3. Set a device count to control how many devices can enroll with this installer.
  4. Run the installer on the target machine. The agent enrolls automatically with the correct organization and site — no enrollment commands needed.
Section titled “Public Installer Links”

You can generate a shareable download URL for an enrollment key so that site contacts can install the agent without needing access to the Breeze dashboard.

  • From the enrollment key details, click Copy Public Link or use the API (POST /enrollment-keys/:id/installer-link).
  • Share the link with on-site contacts via email, chat, or documentation.
  • Links are token-authenticated and rate-limited to prevent abuse.
Section titled “Short Enrollment Links”

Public installer links can also be issued as short, human-friendly URLs of the form https://breeze.yourdomain.com/s/<code>. The short link automatically delivers the right installer for the requester’s platform (Windows MSI or macOS PKG), respects the enrollment key’s usage limits, and is one-time-use by default.

Short codes are issued alongside long-form public links — copy the short URL from the enrollment key details page and share it however you like. Each visit increments the underlying enrollment key’s usage count atomically, so you cannot exceed the configured maxUsage.

macOS GUI Installer

Section titled “macOS GUI Installer”

For onboarding Macs the same way you’d install any other native macOS app, Breeze provides a Swift-based GUI installer (Breeze Installer.app). A site contact opens the app, confirms the install with Touch ID, and the agent is enrolled and started — no Terminal commands.

The GUI installer uses bootstrap tokens generated server-side from an enrollment key, so the same usage-limit and site-pinning guarantees as MSI/PKG installers apply.

What Gets Installed

Section titled “What Gets Installed”

All platform installers (MSI, PKG, and manual service install) include two components:

ComponentDescription
Breeze AgentThe main service that communicates with the Breeze server, runs commands, and reports device status.
WatchdogA companion service that monitors the agent and automatically restarts it after crashes or hangs.

The watchdog runs alongside the agent as a separate process. You do not need to configure it — it starts automatically with the agent service. See the Watchdog documentation for details.

When running breeze-agent service install manually, the agent fetches the matching-version watchdog binary from GitHub releases if one is not already present next to the agent executable. If you need to skip this (for example on an air-gapped host), pass --no-watchdog:

Terminal window
sudo ./breeze-agent service install --no-watchdog

If a previously agent-only install needs the watchdog added, re-run breeze-agent service install. This reinstalls the agent binary and restarts the agent service (safe for upgrades) and registers the missing watchdog. To add only the watchdog without touching the agent service, run breeze-watchdog service install directly.

What Enrollment Does

Section titled “What Enrollment Does”

During enrollment, the agent:

  1. Sends system information (hostname, OS, architecture) to the API
  2. Validates the enrollment secret
  3. Receives a unique brz_ bearer token
  4. Stores configuration in /etc/breeze/agent.yaml (Linux), /Library/Application Support/Breeze/agent.yaml (macOS), or C:\ProgramData\Breeze\agent.yaml (Windows)
  5. Stores secrets in a separate secrets.yaml file with 0600 permissions
  6. Sets file permissions: 0750 for directory, 0640 for config file (agent.yaml), 0600 for secrets file (secrets.yaml)

Verifying Installation

Section titled “Verifying Installation”
Terminal window
# Check service status
sudo systemctl status breeze-agent  # Linux
sudo launchctl list | grep breeze   # macOS
Get-Service breeze-agent             # Windows


# Check agent version
breeze-agent version


# View agent logs
sudo journalctl -u breeze-agent -f  # Linux
sudo log show --predicate 'process == "breeze-agent"' --last 1h  # macOS

The device should appear in your Breeze dashboard within 60 seconds of enrollment.

Configuration File

Section titled “Configuration File”

After enrollment, the agent stores its configuration at:

OSConfig PathSecrets Path
Linux/etc/breeze/agent.yaml/etc/breeze/secrets.yaml
macOS/Library/Application Support/Breeze/agent.yaml/Library/Application Support/Breeze/secrets.yaml
WindowsC:\ProgramData\Breeze\agent.yamlC:\ProgramData\Breeze\secrets.yaml
# agent.yaml (0640 — readable by Breeze Helper)
server_url: "https://breeze.yourdomain.com"
agent_id: "hex-agent-id"
auth_token: "brz_..."
org_id: "uuid-..."
site_id: "uuid-..."
# secrets.yaml (0600 — root only)
auth_token: "brz_..."