Building from Source

Prerequisites

• Go 1.26.6 or later
• 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

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