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

Platform	Architecture	Binary
Linux	amd64	`breeze-agent-linux-amd64`
Linux	arm64	`breeze-agent-linux-arm64`
macOS	amd64 (Intel)	`breeze-agent-darwin-amd64`
macOS	arm64 (Apple Silicon)	`breeze-agent-darwin-arm64`
Windows	amd64	`breeze-agent-windows-amd64.exe`

Quick Install

# 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

# Download the agent
curl -fsSL -o breeze-agent \
  https://breeze.yourdomain.com/api/v1/agents/download/darwin/arm64
chmod +x breeze-agent

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

sudo ./breeze-agent service install

# Download the agent
Invoke-WebRequest -Uri "https://breeze.yourdomain.com/api/v1/agents/download/windows/amd64" `
  -OutFile "breeze-agent.exe"

# Enroll (run as Administrator)
.\breeze-agent.exe enroll YOUR_ENROLLMENT_KEY `
  --server https://breeze.yourdomain.com `
  --enrollment-secret YOUR_ENROLLMENT_SECRET

# Install as a Windows Service
.\breeze-agent.exe service install

Alternatively, use the MSI installer for silent deployment:

msiexec /i breeze-agent.msi /qn `
  SERVER_URL=https://breeze.yourdomain.com `
  ENROLLMENT_KEY=YOUR_ENROLLMENT_KEY

Pre-Configured Installers

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

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

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.

What Gets Installed

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

Component	Description
Breeze Agent	The main service that communicates with the Breeze server, runs commands, and reports device status.
Watchdog	A 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:

Linux / macOS
Windows

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

.\breeze-agent.exe 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

During enrollment, the agent:

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

Verifying Installation

# 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

After enrollment, the agent stores its configuration at:

OS	Config Path	Secrets Path
Linux	`/etc/breeze/agent.yaml`	`/etc/breeze/secrets.yaml`
macOS	`/Library/Application Support/Breeze/agent.yaml`	`/Library/Application Support/Breeze/secrets.yaml`
Windows	`C:\ProgramData\Breeze\agent.yaml`	`C:\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_..."