Prerequisites

Server Requirements

Server sizing only

This table covers the Breeze server (API, web, PostgreSQL, Redis, and the reverse proxy). It says nothing about agent-side footprint on the machines you’re monitoring, which is separate and much smaller.

Resource	Floor	Baseline (small MSP)
CPU	2 x86-64 vCPU	4 vCPU
RAM	4 GiB	8 GiB
Disk	20 GiB free in the install directory	60 GiB SSD-backed, plus snapshot headroom
OS	Ubuntu 22.04+ / Debian 12+	Ubuntu 24.04 LTS
Network	Public IP, ports 80/443 open, NTP	Static IP with DNS A record, TLS reverse proxy, NTP

The CPU / RAM / Disk Floor values are what guided-setup.sh checks before install: below them it warns and, without an explicit “continue anyway” (defaulted to no, including in unattended --yes runs), the install stops. They’re a warning threshold, not a tested capacity limit. The OS and Network rows are general recommendations — the script doesn’t check them.

The CPU / RAM / Disk Baseline values are a real-world small-MSP data point, contributed via #3930: a two-person MSP settled on 4 vCPU / 8 GiB RAM / 60 GiB SSD, plus extra headroom for snapshots. The jump from the 20 GiB disk floor reflects PostgreSQL, Redis’s append-only file, container images, logs, upgrade image churn, and (on ZFS) snapshots all competing for the same volume — 20 GiB leaves little margin for any of that.

Breeze does not publish arm64 server images — GHCR images are amd64 only. On Apple Silicon, use docker-compose.override.yml.local-build to build native arm64 images instead (see Docker Deployment).

No per-agent sizing formula

There isn’t yet enough controlled data to turn “N agents” into a hardware number. Validate your sizing against actual agent count, event volume, retention window, remote-control usage, and backup policy, and scale up if you see resource pressure.

Redis in particular ships with a 256mb default maxmemory and a noeviction policy (see REDIS_MAXMEMORY) — job data queues rather than getting silently dropped, but a fleet outgrowing the default will need it raised, or writes start failing. If you have real-world sizing data for your fleet size, open an issue — we’d like to build this table out with more data points.

Required Software

Docker & Docker Compose

Breeze runs entirely in Docker containers. Install Docker Engine with the Compose plugin:

Ubuntu/Debian

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in, then verify:
docker compose version

macOS

# Install Docker Desktop from https://docker.com/products/docker-desktop
# Or via Homebrew:
brew install --cask docker

Node.js & pnpm (Development Only)

Node.js and pnpm are not required for standard Docker deployments — the API container handles database migrations automatically on startup via AUTO_MIGRATE=true (the default).

You only need these tools if you are doing local development or managing migrations manually:

# Install Node 20+
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install pnpm
npm install -g pnpm@9

Git

sudo apt-get install -y git

DNS Configuration

Point your domain to your server’s public IP:

A   breeze.yourdomain.com    → 203.0.113.10

Caddy will automatically provision a TLS certificate from Let’s Encrypt once DNS resolves.

Optional: Go Toolchain

Only needed if building the agent from source (pre-built binaries are available):

# Go 1.26.6+
wget https://go.dev/dl/go1.26.6.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.26.6.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

Firewall Rules

Ensure these ports are accessible:

Port	Protocol	Purpose
80	TCP	HTTP → HTTPS redirect (Caddy)
443	TCP	HTTPS (web UI, API, agent WebSocket)
3478	TCP/UDP	TURN server (coturn — required only if using WebRTC remote desktop)
49152–65535	UDP	TURN media relay port range (coturn — required only if using TURN)

All other services (PostgreSQL, Redis, Prometheus, Grafana) bind to 127.0.0.1 and are not exposed publicly.