Building from Source

Prerequisites

• Go 1.26.9 or later. With the default GOTOOLCHAIN=auto, go build fetches 1.26.9 on its own; with GOTOOLCHAIN=local, install Go 1.26.9 first.
• Make
• (Optional) go-winres for Windows resource embedding
• (Optional) WiX Toolset + PowerShell for MSI packaging

Build Commands

cd agent

# Build for current platform
make build

# Build for all platforms (Linux, macOS, Windows)
make build-all

# Build for specific platforms
make build-linux    # linux/amd64 + linux/arm64
make build-darwin   # darwin/amd64 + darwin/arm64
make build-windows  # windows/amd64

Output binaries are placed in agent/bin/.

Cross-Platform Builds

Target	Command	Output
Linux amd64	make build-linux	bin/breeze-agent-linux-amd64
Linux arm64	make build-linux	bin/breeze-agent-linux-arm64
macOS Intel	make build-darwin	bin/breeze-agent-darwin-amd64
macOS Apple Silicon	make build-darwin	bin/breeze-agent-darwin-arm64
Windows amd64	make build-windows	bin/breeze-agent-windows-amd64.exe

Other Agent Binaries

make build (and plain make build-all) compiles the main breeze-agent binary plus its companion processes in one pass. Each companion also has its own current-platform and all-platforms targets:

Binary	Purpose	Current-platform target	All-platforms target
breeze-desktop-helper	The end-user Helper process (AI chat, screenshots, tray icon) – see Helper	make build-desktop-helper	make build-all-desktop-helper
breeze-backup	Runs backup, restore, and verify jobs dispatched by the agent – see Backup Management	make build-backup	make build-all-backup
breeze-watchdog	Restarts the agent service if it stops responding	make build-watchdog	make build-watchdog-linux / -darwin / -windows
breeze-user-helper	Windows-only sibling of breeze-agent that launches into the logged-in user’s session (an asInvoker manifest, so it isn’t blocked by UAC token filtering)	make build-windows-user-helper	– (Windows-only)

Note

make build-all-desktop-helper only builds the macOS (darwin amd64/arm64) variants – there is no Linux or Windows target for it yet. make build-all-backup covers all three platforms.

Windows MSI Installer

To build an MSI installer for enterprise deployment:

# On Windows with WiX installed:
make build-windows-msi VERSION=0.2.0

This produces dist/breeze-agent.msi for silent deployment via GPO or SCCM.

Version Embedding

The build embeds the version number via linker flags:

VERSION ?= 0.5.0
LDFLAGS := -ldflags "-X main.version=$(VERSION)"

Override at build time:

make build VERSION=1.0.0

Display Branding

Operators building their own agent can set the display text Windows and Linux show for the agent and watchdog services, so your own name appears where users and admins read it. This is set at build time and is optional: a build with no branding values is identical to the official one.

Only display text can be branded. Service names (BreezeAgent, BreezeWatchdog), executable names, folders, the MSI’s ProductName and UpgradeCode stay fixed, so updates, the installer and reliability scoring keep recognising the agent.

Binaries. Build through agent/scripts/build-edition.sh with any of these environment variables set:

Variable	Sets
BREEZE_BRAND_AGENT_DISPLAY_NAME	Agent service display name
BREEZE_BRAND_AGENT_DESCRIPTION	Agent service description
BREEZE_BRAND_WATCHDOG_DISPLAY_NAME	Watchdog service display name
BREEZE_BRAND_WATCHDOG_DESCRIPTION	Watchdog service description
BREEZE_BRAND_AGENT_CLI_SHORT	One-line summary in the agent’s command help
BREEZE_BRAND_WATCHDOG_CLI_SHORT	One-line summary in the watchdog’s command help

Windows MSI. agent/installer/build-msi.ps1 accepts -Manufacturer (the publisher shown in Programs and Features), -PackageDescription, -AgentServiceDisplayName, -AgentServiceDescription, -WatchdogServiceDisplayName and -WatchdogServiceDescription. A service parameter left blank takes the matching BREEZE_BRAND_* value, and a parameter that differs from it is refused, so the MSI and the binaries always carry the same names.

A value is refused if it is longer than 256 bytes or contains a control character, a single or double quote, a backslash or a percent sign. The MSI also refuses square brackets, braces, $( and !(. Existing Linux installs keep their old service description until a later agent version rewrites the unit.

Note

The agent source code is in agent/ at the repository root, not in apps/agent/. Both directories exist but serve different purposes.

Project Structure

agent/
├── cmd/breeze-agent/     # Entry point
├── internal/
│   ├── agent/            # Core agent loop
│   ├── commands/         # Command execution
│   ├── config/           # Configuration management
│   ├── discovery/        # Network discovery scanner
│   ├── heartbeat/        # Telemetry collection
│   ├── ipc/              # Inter-process communication
│   ├── mtls/             # mTLS certificate management
│   ├── pty/              # Terminal PTY handling
│   ├── sessionbroker/    # User session management
│   ├── transfer/         # File transfer
│   └── userhelper/       # User-mode helper process
├── scripts/install/      # Service installation scripts
├── service/              # systemd/launchd unit files
└── Makefile

Running in Development

cd agent
make run

This runs the agent directly without installing it as a service. Useful for testing against a local Breeze server.

Testing

cd agent
make test        # Run all tests
make test-ipc    # Run IPC and session broker tests
make lint        # Run golangci-lint
make fmt         # Format code