Perses: a CNCF dashboard tool that keeps dashboards as code

The problem Perses targets: dashboards that only exist inside a UI

Most observability dashboards are created by clicking. The result lives in a database owned by the dashboard product, and the only way to review a change is to look at a screenshot or open the same UI. Perses takes the opposite position. The README describes the project as "first and foremost a dashboard tool" and lists a GitOps-friendly goal: SDKs, CI/CD libraries, static validation and a native CLI. That is the whole argument. A dashboard is a file you can diff, a change you can review, and a build step that fails when the definition is invalid.

The audience follows from that. Platform and SRE teams that already treat Prometheus rules and Kubernetes manifests as versioned artifacts are the natural users. So are teams that want one dashboard surface across metrics, traces, logs and profiles instead of four separate UIs. The README states that Perses currently supports Prometheus metrics, Tempo traces, Loki for logs and Pyroscope for profiling, which it calls all four observability pillars in one place. Anyone who only needs a single Prometheus graph and never intends to keep it in Git gets little from the design.

How Perses separates the dashboard spec, the plugins and the API server

The repository layout shows the split clearly. The Go server lives under cmd/ and internal/, the React frontend under ui/, the CUE SDK under cue/, the Go SDK under go-sdk/, and shared definitions under pkg/. The server is built on the Echo web framework and depends on github.com/perses/spec, which is the dashboard specification as a separate module. That is the mechanism behind the interoperability claim in the README: the format is not buried in the application.

Plugins are the second mechanism. The README says the plugin architecture "enables the externalization of both plugin loading and implementation", and that the core plugins are maintained in the perses/plugins repository rather than here. So a panel type or a data source is not necessarily part of this codebase. When you evaluate Perses, you are evaluating two repositories at once, and the Dockerfile confirms it: it copies a plugins-archive directory into /etc/perses/plugins-archive/ and mounts /etc/perses/plugins as a volume, with the default config at /etc/perses/config.yaml. Plugins are files on disk, not code compiled into the binary.

The Go module also lists cuelang.org/go and github.com/perses/spec, which matches the Dashboard-as-Code story: dashboards can be written in CUE or Go and evaluated into the API's format. The README notes the Go and CUE SDKs "will likely evolve based on the feedback we receive", with expected changes adding utility functions rather than breaking changes. That is a statement of intent, not a compatibility guarantee.

Installing Perses with Docker and loading the first dashboard

The README lists several install paths: precompiled binaries from the GitHub releases page, Docker images on Docker Hub, a Homebrew tap, and a source build. It calls the latest release binary the recommended way. The Docker path is the shortest for a first look. The README gives this exact command, which starts the server in the background on port 8080 bound to localhost:

docker run --name perses -d -p 127.0.0.1:8080:8080 persesdev/perses

After that, open http://localhost:8080 in a browser. The container's entrypoint is /bin/perses with --config=/etc/perses/config.yaml and --log.level=error, so the process starts quietly; if the page does not load, check the container logs rather than expecting output on the terminal. The image exposes 8080 and declares /perses as a volume, which is where the working directory points.

For macOS and Linux, the Homebrew tap installs the server and the CLI as separate formulae. The README gives both commands:

brew install perses/tap/perses
brew install perses/tap/percli

percli is the CLI that talks to the Perses API, and the README points to docs/cli.md for it. If you prefer to build from source, the stated prerequisites are Go 1.26 or greater, NodeJS 22 or greater and npm 10 or greater. The README and the Makefile agree on the build target:

git clone https://github.com/perses/perses.git
cd perses
make build
./bin/perses --config=your_config.yml

make build produces both the server and percli under bin/. Note that go.mod declares go 1.27.1 while the README asks for 1.26 or greater; the module directive is the stricter of the two, so a 1.26 toolchain may refuse to build the module as written. The README does not document a config file schema, so for a first run the container's bundled config is the safer starting point than a hand-written one.

Where Perses is the wrong tool

The most obvious limit is data source coverage. Four backends are supported, and the README says more will come. If your metrics live in something other than Prometheus, or your traces in something other than Tempo, the plugin may not exist yet, and the README does not promise a timeline. Checking the perses/plugins repository before you commit is not optional.

The second limit is maturity. The README says Perses "can now be used" and that the data model reached a stable point, but the recent releases are all v0.55.0-beta variants, and the SDK section explicitly says the SDKs will likely evolve. A pre-1.0 version number means the project has not committed to API stability, and the README's own wording about the data model is a claim about the present, not a compatibility promise for the future.

The third limit is operational. Perses is a server you run, with authentication and authorization available according to the README, and a persistence layer behind it. go.mod pulls in both github.com/go-sql-driver/mysql and github.com/jackc/pgx/v5, so SQL backends are in play, but the README does not describe deployment topologies, backup, or migration between versions. A team without anyone to own that server should weigh the cost against a hosted dashboard product. The README also does not document rollback, so an upgrade path between beta releases is something to test on a copy first.

Perses compared with Grafana, and what actually differs

Grafana is the reference point most teams will use, and the difference is not the feature list. Grafana's model is a server with a database of dashboards, extended by a large plugin catalogue, and its dashboard JSON is exportable but not the primary authoring path. Perses inverts that: the README's stated goal is "an open specification for dashboards" with static validation and SDKs, so the file is the source of truth. If your dashboards are already managed as code in Grafana, the migration question is which format you would rather validate in CI, and Perses answers with a CLI and two SDKs.

The second difference is embedding. The README describes npm packages that let developers embed panels and dashboards into their own UIs, with the Prometheus UI named as a possible future consumer. Grafana's plugin system is broader but is tied to the Grafana runtime. If you are building an internal portal and want a panel component rather than a whole dashboard product, that is a real distinction.

The third is Kubernetes. The README describes a Kubernetes-native mode where dashboard definitions are deployable into and readable from application namespaces via Custom Resource Definitions, pointing at the separate Perses Operator. Grafana has an operator too, but Perses frames CRDs as the primary Kubernetes story rather than an add-on. Either way, you are adopting two projects, not one.

Licence, maintenance and the cost of keeping up

Perses is licensed under Apache-2.0, and the repository ships a LICENSE file at the root. The Dockerfile copies that LICENSE into the image. Apache-2.0 is a permissive licence with an explicit patent grant and requires that you keep the licence and notices when you redistribute. It does not impose copyleft on your own code. What it does not do is grant trademark rights, and the README does not describe a trademark policy, so do not assume you can use the Perses name for a derived product. This is a description of the licence text, not legal advice; if you redistribute Perses inside a commercial product, have counsel read the LICENSE and the NOTICE situation for the plugins you bundle.

Maintenance is visible in the repository rather than in a statement. The last push to main was on 2026-09-28, and the most recent releases are v0.55.0-beta.3 on 2026-09-22, v0.55.0-beta.2 on 2026-09-18 and v0.55.0-beta.1 on 2026-09-16. That is a rapid beta cadence, which cuts both ways: fixes arrive quickly, and the surface you build against moves quickly. The repository is not archived.

Upgrade cost has concrete shapes here. The plugin archive is a directory copied into the image, so a new server version can require a matching plugin set; the README does not describe version skew rules between the server and its plugins. The CLI is a separate binary, and the README pairs percli with the server install, so keeping them on the same release is the safe assumption. The SDKs are the third moving part, and the README's promise is limited to preferring additive changes. Budget for reading the CHANGELOG before each bump.

Editorial conclusion

Adopt Perses if your dashboards need to be reviewed, validated and deployed like the rest of your configuration, and if Prometheus, Tempo, Loki and Pyroscope cover the data you visualise. Do not adopt it if you need a long list of native data source integrations or a stable 1.0 API contract today, because the current releases are beta and the SDKs are still described as evolving. Before committing, verify three things: that the plugin you need exists in the perses/plugins repository, that your chosen persistence backend is documented for your deployment, and that the CLI version you install matches the server version you run, since the README pairs percli with the server release.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. perses/perses on GitHub
3. Project website
4. README
5. Releases