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.

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)