Binary Distribution

Breeze serves agent binaries and viewer installers through its own API. The download source is configurable via BINARY_SOURCE, so downloads work regardless of how you deploy.

Binary Source Modes

Set BINARY_SOURCE to control where downloads come from:

Mode	Description	When to use
github (default)	Agents download directly from GitHub Releases CDN	Most deployments
local	Serve from disk, with optional S3 offload	Distribute binaries from your own infrastructure

GitHub Mode (Default)

No local binaries needed. Download requests redirect to GitHub Releases:

GET /api/v1/agents/download/linux/amd64
→ 302 https://github.com/lanternops/breeze/releases/download/v0.11.3/breeze-agent-linux-amd64

The release version is determined by BINARY_VERSION or BREEZE_VERSION. If neither is set, redirects to the latest release.

On startup, the API calls GitHub’s Releases API to register the current version’s checksums in the agent_versions table, so agents know when a new version is available.

Note

In both modes, registering a release also promotes it to the fleet upgrade target by default. Set AGENT_AUTO_PROMOTE=false to register binaries without promoting them, then promote explicitly once you’ve verified — see Controlled agent fleet rollout.

Manifest trust root

In production, GitHub mode requires the RELEASE_ARTIFACT_MANIFEST_PUBLIC_KEYS env var. This is the base64 SPKI of the Ed25519 public key that signs our release manifests. The API verifies every fetched manifest against this key before trusting its checksums, so a compromised GitHub release alone can’t deliver tampered binaries.

For the official Breeze releases, use the published trust anchor:

RELEASE_ARTIFACT_MANIFEST_PUBLIC_KEYS=yzx8ftmcls6uBetFC5SYnZhBo+cbur3IX50TbBthTso=

This is a public key (also embedded in the agent and CI), so it is safe to commit. Only override it if you build and sign your own binaries. The API refuses to start in production without it. During a signing-key rotation you can trust multiple keys at once by comma-separating them (RELEASE_ARTIFACT_MANIFEST_PUBLIC_KEYS=old,new).

Local Mode

Binaries are served from disk. The API reads from these directories:

Variable	Default	Contents
AGENT_BINARY_DIR	./agent/bin	Agent binaries (e.g. breeze-agent-linux-amd64)
VIEWER_BINARY_DIR	./viewer/bin	Viewer installers (e.g. breeze-viewer-macos.dmg)
HELPER_BINARY_DIR	/data/binaries/helper	Helper binaries (e.g. breeze-helper-windows.msi)

On startup, the API:

1. Scans AGENT_BINARY_DIR for agent binaries
2. Computes SHA-256 checksums and registers each binary in the agent_versions table
3. Marks them as the latest version
4. If S3 is configured, syncs both directories to your S3 bucket

Caution

If the API detects a version mismatch between the binaries volume and BREEZE_VERSION (e.g. the init container wasn’t refreshed during an upgrade), it automatically falls back to GitHub Releases so agents still get the correct binary.

Docker Compose Setup

The docker-compose.yml includes a binaries init container that bundles agent and viewer binaries into a shared volume:

services:
  binaries-init:
    image: ghcr.io/lanternops/breeze/binaries:${BREEZE_VERSION:-latest}
    pull_policy: always
    volumes:
      - binaries:/target
    restart: "no"

  api:
    volumes:
      - binaries:/data/binaries:ro
    environment:
      BINARY_SOURCE: ${BINARY_SOURCE:-github}
      AGENT_BINARY_DIR: /data/binaries/agent
      VIEWER_BINARY_DIR: /data/binaries/viewer
      HELPER_BINARY_DIR: /data/binaries/helper
depends_on:
      binaries-init:
        condition: service_completed_successfully

The init container:

1. Runs on every docker compose up (pull_policy: always ensures the latest image is pulled)
2. Copies bundled binaries to the shared binaries volume
3. Exits (restart: “no”)
4. The API mounts the volume read-only

When BINARY_SOURCE=github (default), the API ignores the local volume and syncs versions from GitHub Releases instead. The volume is only used when BINARY_SOURCE=local.

S3 Offload (Optional)

When BINARY_SOURCE=local and S3 credentials are configured, Breeze:

1. On startup: syncs local binaries to your S3 bucket
2. On download: returns a 302 redirect to a presigned S3 URL (falls back to disk if presigning fails)

This offloads download bandwidth from your API server to S3/R2/MinIO.

Variable	Default	Description
S3_ENDPOINT	—	S3-compatible endpoint
S3_ACCESS_KEY	—	Access key
S3_SECRET_KEY	—	Secret key
S3_BUCKET	—	Bucket name
S3_REGION	us-east-1	Bucket region
S3_PRESIGN_TTL	900	Presigned URL expiration in seconds (15 min)

S3 is activated when S3_BUCKET, S3_ACCESS_KEY, and S3_SECRET_KEY are all set. Files are uploaded to:

• s3://{bucket}/agent/ — agent binaries
• s3://{bucket}/viewer/ — viewer installers

Download Endpoints

Agent Binaries

GET /api/v1/agents/download/:os/:arch

Parameter	Values
os	linux, darwin, windows
arch	amd64, arm64

Viewer Installers

GET /api/v1/viewers/download/:platform

Parameter	Values	File
platform	macos	breeze-viewer-macos.dmg
	windows	breeze-viewer-windows.msi
	linux	breeze-viewer-linux.AppImage

Helper Binaries

GET /api/v1/agents/download/helper/:os/:arch

Parameter	Values
os	linux, darwin, windows
arch	amd64, arm64

Helper binaries are companion processes used for remote desktop in headless/service contexts (Session 0 on Windows, LaunchDaemon on macOS, systemd on Linux).

Backup Binary

The breeze-backup binary handles enterprise backup operations (Hyper-V, MSSQL, system image, cloud-to-cloud). It is bundled in installers, not downloaded separately:

• Windows MSI: installed to the same directory as breeze-agent.exe
• macOS .pkg: installed to /usr/local/bin/breeze-backup
• Linux: included alongside the agent binary

The backup binary communicates with the main agent over HMAC-signed IPC. It is not served through the download API — it ships as part of the agent installer package.

Install Script

GET /api/v1/agents/install.sh

One-line agent installer that auto-detects OS/arch, downloads the binary, enrolls, and installs as a system service.

Decision Guide

Standard (Default)

Agents download directly from GitHub. No configuration needed:

.env

# BINARY_SOURCE=github  (default, no change needed)

Own Infrastructure (S3/CDN)

Distribute binaries from your own S3-compatible storage:

.env

BINARY_SOURCE=local
S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
S3_ACCESS_KEY=AKIA...
S3_SECRET_KEY=...
S3_BUCKET=breeze-binaries

On upgrade, the init container pulls the new binaries image, copies to the volume, and the API syncs to S3 automatically.

Local Dev

Build the agent and binaries are served from ./agent/bin:

cd agent && make build-all
# API serves from AGENT_BINARY_DIR=./agent/bin (default)