Perses

Last reviewed Sep 13, 2026 · 887 words

Perses is not a Grafana replacement for a homelab in 2026, and it does not try to be. It is a CNCF project that treats a dashboard as a versioned JSON or YAML file with a published schema, validated in CI and deployed by pull request, and if that sentence made you nod you are the audience. If you want to click "add panel" and drag a graph around, Grafana still does that better, with roughly 10 times the panel types and a decade of head start. Perses launched in 2022, sits at 2,417 stars under Apache-2.0, ships as a single Go binary that idles in about 256 MB, and its governance is the reason it exists.

Why a second dashboard tool exists at all

Grafana's dashboard JSON is an export format, not a specification. It is huge, changes between versions, and there is no schema you can validate against before deploying. Teams that try to manage 200 Grafana dashboards in git end up with a pile of 3,000-line JSON files nobody can review. Perses was built by people who lived that, at Amadeus and then with the Prometheus maintainers, and the core deliverable is the specification: a documented data model for dashboards, panels, variables and datasources, plus a CUE-based plugin schema so a broken dashboard fails validation instead of rendering an empty panel in production.

The second reason is licensing. Grafana moved to AGPL in 2021; Perses stayed Apache-2.0 and lives under CNCF governance rather than a single vendor. For a company embedding dashboards in a product that matters a great deal. For your basement it does not.

What the dashboards-as-code workflow looks like

You write the dashboard, not click it. A minimal one with a single Prometheus time series panel is about 30 lines of YAML, and the percli tool validates and applies it:

percli login http://localhost:8080
percli apply -f dashboards/node-overview.yaml

Perses also ships a Go SDK and a CUE SDK, so a dashboard can be a small program that generates panels from a list of services, which is where the approach pays off. Ten near-identical per-service dashboards become one loop. Changes go through code review with a real diff. Rollback is git revert. The catalogue's "GitOps-friendly" tag is accurate rather than marketing.

There is a web UI as well, and you can build dashboards in it, but the UI is thin next to Grafana's and the project's own direction treats it as a viewer and editor for what ultimately lives in files.

Where it falls short of Grafana today

The alerting row is the one that ends most homelab evaluations. Perses draws graphs; it does not page you. You keep Alertmanager for that, which is fine if you already run Prometheus and have alert rules there, and a step backward if your alerts currently live in Grafana. The datasource row is the other: if your dashboards mix Prometheus with Loki logs or an InfluxDB from your solar inverter, Perses cannot draw half of them.

There is a migration tool that converts Grafana dashboard JSON to Perses format. It handles the common panels and leaves the rest as unsupported placeholders, so treat it as a starting point rather than a lift-and-shift.

Running it

The Docker image is straightforward: expose port 8080, mount a config file, and by default it stores dashboards on the filesystem, with a SQL database option for multi-instance deployments. Point it at your existing Prometheus and it works in about 5 minutes. On Kubernetes there is an operator that reconciles dashboards from custom resources, which is the deployment the project clearly cares most about. Resource use is modest; the Go binary plus a few dozen dashboards stays well inside the catalogue's 256 MB.

Nothing here replaces the collection layer. Perses sits exactly where Grafana sits, on top of Prometheus, and the Grafana vs Prometheus explainer applies unchanged with the name swapped.

What I'd do

For a home setup with a handful of dashboards, run Grafana and stop reading. For a team already keeping infrastructure in git, with more than 20 dashboards and a Prometheus-only metrics stack, run Perses alongside Grafana for one quarter: move the per-service dashboards that you generate from a list, keep the exploratory ones in Grafana, and decide at the end whether the validated schema saved you enough review pain to justify two tools. My bet is that Perses becomes the standard for dashboards you ship with software, the way a Helm chart ships alert rules today, while Grafana remains the thing humans open at 3 a.m. Both belong in the monitoring category and they are not really fighting over the same job.