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

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_..."