Platforms

Ongrid ships two binaries with very different platform stories.

• ongrid (the cloud manager) is a Linux + Docker workload. It is meant to live in a container, behind nginx, with MySQL underneath. There is no first-class Windows or macOS server build.
• ongrid-edge (the edge agent) is a single static binary that runs on every host you want to observe. It cross-compiles to four targets out of the box: Linux on amd64 / arm64 and macOS on amd64 / arm64. Production-grade install only on Linux + systemd; macOS targets exist so developers can run the agent on their laptop while iterating.

Support matrix

Component	linux/amd64	linux/arm64	darwin/amd64	darwin/arm64	Windows
ongrid (manager image)	yes	tested as build target	no	no	no
ongrid-edge (binary, supervised)	yes	yes	dev-only, manual	dev-only, manual	no
promtail plugin (logs)	yes	yes	no (upstream gap)	no (upstream gap)	no
node_exporter plugin (host metrics)	yes	yes	no (upstream gap)	no (upstream gap)	no
process-exporter plugin (proc metrics)	yes	yes	no (upstream gap)	no (upstream gap)	no
otelcol-contrib plugin (traces)	yes	yes	no (not bundled)	no (not bundled)	no

The four edge cross-compile targets come straight from the Makefile:

build-edge-linux-amd64
build-edge-linux-arm64
build-edge-darwin-amd64
build-edge-darwin-arm64

make build-edge-all runs all four; make package produces the release tarball that bundles every target plus the Linux-only plugin binaries.

Why no Windows / BSD edge?

The agent itself is pure Go and would compile cleanly; the gap is the plugin bundle. promtail, node_exporter, process-exporter, and otelcol-contrib all ship Linux-only artefacts in their upstream releases. Without those four, the Logs / Monitor / Traces panels stay empty even after the agent is connected. We would rather not ship a half-working install than carry a hidden-disabled platform.

If you have a strong Windows or FreeBSD use case, open an issue on github.com/ongridio/ongrid — pluggable bundlers are tracked under ADR-015.

Cloud side requirements

Anywhere you can run Docker Engine 24+ and Docker Compose v2 will host the manager. We test on:

• Ubuntu 22.04 LTS, 24.04 LTS
• Debian 12 (bookworm)
• RHEL 9, Rocky Linux 9, AlmaLinux 9

Memory floor: 4 GB. Disk floor: 20 GB (most of which is Prometheus + Loki retention, see Linux (server)).

Edge side requirements

The official curl-pipe installer (deploy/install/edge/install.sh) explicitly only handles Linux:

if [[ "$OS" != "linux" ]]; then
    log_error "only linux is supported by this installer; got: $OS"
    exit 1
fi

That installer drops a systemd unit (/etc/systemd/system/ongrid-edge.service), creates a system user ongrid-edge, and supervises the agent via systemd with Restart=always. macOS hosts can still run the binary by hand for development — see macOS (edge dev) — but you do not get the supervised service, the journald log source, or the plugin bundle.

Choosing the right page

• Installing the manager? → Linux (server)
• Installing an edge agent on a real Linux host? → Linux (edge)
• Running the agent on a Mac for development? → macOS (edge dev)
• Deploying everything on Kubernetes? → Kubernetes
• Air-gapped or private container registry? → Air-gapped / on-prem

Versioning policy

The manager and the agent share a single VERSION file (/Users/.../ongrid/VERSION) and are released as one tarball. An edge agent older than its manager will keep working: every tunnel RPC is versioned, and the manager treats unknown reply fields as zero values. An edge agent newer than its manager is unsupported — upgrade the manager first.

See Upgrade for the staged-swap-then-rollback model (ADR-024).