Cortex

Last reviewed Sep 13, 2026 · 916 words

Do not run Cortex in a homelab. That is not a slight on the project, which is a CNCF-graduated system that stores Prometheus metrics for tens of millions of active series across many teams, but a plain reading of what it is for: multi-tenant, horizontally scaled, object-storage-backed metrics for organizations whose Prometheus servers stopped fitting in one box. Everything about its design, from the seven-plus microservices to the mandatory S3-compatible bucket, is a cost that only pays off past a scale most readers of this site will never reach. If you want long retention for a handful of Prometheus instances, VictoriaMetrics does it in one binary, and the rest of this guide is mostly about why.

What Cortex actually is

Prometheus is a single-node database. It scrapes, stores locally, and answers PromQL. It does not cluster, does not share storage, and its retention is bounded by one disk. Cortex was built in 2016 to accept Prometheus's remote-write stream and provide what the single node cannot: a global query view across many Prometheus servers, retention measured in years in cheap object storage, high availability with replicated ingesters, and tenant isolation so that team A cannot see or overload team B's metrics.

It does this with distinct components. A distributor receives writes and shards them by series, ingesters hold recent data in memory and cut TSDB blocks, a compactor merges blocks in the bucket, a store-gateway serves historical blocks, queriers and a query-frontend execute PromQL with caching and splitting, and a ruler evaluates alerting rules per tenant. Tenancy is a header, X-Scope-OrgID, on every request. The API is Prometheus-compatible, so Grafana points at it exactly as it would at Prometheus, with the Grafana vs Prometheus roles unchanged.

Mimir is Cortex's successor, and Cortex knows it

In 2022 Grafana Labs, the main contributor, forked Cortex into Mimir under AGPL and moved its engineers there. Mimir got the performance work, the simplified deployment modes, the Helm charts that people actually use, and the documentation budget. Cortex continued under Apache-2.0 with a smaller maintainer group, and the two codebases still resemble each other closely enough that operational knowledge transfers.

The honest picture of who runs Cortex in 2026: organizations that adopted it before the fork and have no reason to migrate, managed services that were built on it (Amazon Managed Service for Prometheus started as Cortex under the hood), and teams for whom the Apache license is a hard requirement that rules Mimir out. If none of those describe you and you are at true multi-tenant scale, Mimir is the default pick, and I say that with no enthusiasm for the license change.

Single-binary mode exists and is still not small

You can run Cortex with -target=all, which starts every component in one process, and point it at a local filesystem bucket. That works and is how the project's getting-started guide demonstrates itself. It still needs about 1 GB of RAM at idle before any series arrive, an object store abstraction over a directory, and a config file that runs to a few hundred lines once you set retention, limits and compaction. For comparison, a Prometheus with --storage.tsdb.retention.time=2y on an SSD holds years of a homelab's metrics in a few GB and needs no additional process.

The scale at which Cortex begins to make sense is roughly: more than one Prometheus that must be queried as one, more than one team needing isolation, or more than a few million active series. Below that, the operational surface is pure overhead.

The real alternatives for long retention

For a self-hoster whose Prometheus disk is filling or who wants 2 or 3 sites in one Grafana, three options in rising order of complexity. VictoriaMetrics: a single binary, accepts remote write, compresses far better than TSDB, and is what I recommend for nearly everyone. Thanos: a sidecar next to each existing Prometheus that uploads blocks to object storage plus a querier that fans out; it keeps Prometheus in place and adds global view and long retention with fewer moving parts than Cortex. Mimir: the full multi-tenant architecture, when you genuinely need it.

Cortex slots in only as the Apache-licensed variant of the third option.

If you are going to run it anyway

Use the Helm chart on Kubernetes rather than Docker Compose, use real object storage (MinIO if it must be local), set per-tenant limits before the first team overloads an ingester, and read the Cortex documentation on the ingester lifecycle before your first restart, because ingesters hold unflushed data in memory and a careless rollout loses it. Give ingesters the most memory of any component; 4 GB per replica is a realistic floor under load. Budget an engineer's ongoing attention, not an evening.

What I'd do

Homelab or small business: Prometheus with 1 to 2 years of retention on an SSD, and if you outgrow that, remote-write into a single VictoriaMetrics instance. Multiple sites or teams: Thanos sidecars if the Prometheus servers already exist, Mimir if you are designing from scratch. Cortex only when an Apache-2.0 license is non-negotiable or it is already running and healthy, in which case leave it alone; a working Cortex is not worth a migration for its own sake.