Distr: a self-hostable control plane for shipping software into customer clouds
The Open Source control plane for self-hosted, BYOC, and on-prem deployments. Everything you need to distribute applications to self-hosted customers out of the box. Supporting Docker Compose, Docker Swarm and Helm based applications.
At a glance
- What is it?
- Distr is an Apache-2.0 Go control plane that pushes Docker Compose, Docker Swarm and Helm deployments into environments you do not own. It is a good fit if you already sell on-prem or BYOC installs and are doing it by hand; it is not a general-purpose CI or a Kubernetes operator.
- Who is it for?
- Adopt Distr if you sell software that runs inside customer infrastructure and you currently ship it over email, shared drives or a hand-rolled script per customer. Do not adopt it if your delivery target is a single cloud you control, or if you need an SDK in a language other than JavaScript today.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Distr is aimed at: software that has to run inside someone else's network
Most deployment tooling assumes you own the target. Distr starts from the opposite assumption. The README describes it as a platform that helps software and AI companies distribute applications to customers in "complex, self-managed environments", and lists three use cases: on-premises, VPC and self-managed deployments; Bring Your Own Cloud automation; and edge and fleet management. Those are situations where the vendor cannot open a tunnel into the customer's cluster, cannot assume a public ingress, and often cannot assume the customer has a Kubernetes administrator on staff.
The practical consequence is that the vendor needs a place to hold the catalogue of what has been shipped to whom, which version each customer is running, and a mechanism that reaches into the customer environment to apply changes. Distr packages that as a control plane (the Hub) plus an optional agent that runs on the customer side. The intended user is a vendor's platform or release engineer, not the customer's own ops team, although the README notes that customers can be given a white-label portal to control their own deployments or download artifacts.
If your product is a SaaS application you operate yourself, Distr has nothing to do here. The whole design assumes a boundary between your infrastructure and the customer's, and that boundary is the thing it manages.
Hub, agent, registry: the four moving parts in the architecture diagram
The repository's architecture diagram splits into three groups. Inside "Distr Cloud or Your Cloud" sit the Hub, a PostgreSQL database, Loki for log storage, a Distr OCI registry, and object storage. The Hub connects to all of them: PostgreSQL supplies relational state, Loki holds logs, and the OCI registry is backed by the object store.
On the customer side there are two shapes. The first is a customer cloud running the Distr Agent, which in turn talks to "Your Application". The second is a fully self-managed customer that only runs an OCI client, with no agent at all. That distinction matters when you evaluate the product: the agent is what enables deployment automation, log and metric collection and remote troubleshooting, per the feature list. A customer who refuses to run an agent can still pull artifacts from the registry, but you lose the automation and observability half of the platform.
The Hub also exposes a REST API, and the README points to https://app.distr.sh/docs for the full reference. A first-party SDK exists for JavaScript only, installed with npm install --save @distr-sh/distr-sdk, and the README states that more languages and frameworks are "on the roadmap". Treat that as a real constraint if your tooling is Python, Go or Java: you would be calling the REST API directly and maintaining your own client.
Getting a Hub running with Docker Compose or Helm
The README gives two self-hosting paths. The Docker one is a three-command quickstart: create a directory, fetch a release tarball, and bring the stack up.
mkdir distr && cd distr && curl -fsSL https://github.com/distr-sh/distr/releases/latest/download/deploy-quickstart.tar | tar -x docker compose up -d
The README instructs you to "make necessary changes to the .env file" between those two steps, and the example deployment lives in deploy/docker/quickstart in the repository. The Hub image itself is published via ghcr.io.
The Kubernetes path uses a Helm chart also distributed through ghcr.io:
helm upgrade --install --wait --namespace distr --create-namespace \ distr oci://ghcr.io/distr-sh/charts/distr \ --set postgresql.enabled=true --set rustfs.enabled=true
Those two values are the ones the README shows explicitly: postgresql.enabled and rustfs.enabled. The README says that for a quick test you do not have to modify the values, but that production use requires revisiting "all available configuration values" in the reference values.yaml on Artifact Hub. The chart source is in deploy/charts/distr.
After the stack is up, the README says to register the first account at http://localhost:8080/register. That is the whole documented bootstrap. Note what is not in the quickstart: TLS termination, backup of PostgreSQL and object storage, and how the OCI registry is exposed to customers outside your network. Those are left to you, and they are the parts that decide whether the deployment survives contact with real customers.
License management and the container registry are the two features worth scrutinising
The feature list includes "License Management: Distribute specific versions of your application to specific customers", and a container registry for OCI-compatible artifacts with granular access control and analytics. Together these are the commercial core: you decide which customer sees which version, and the registry enforces who can pull what.
The README is thin on the mechanics of both. It does not describe how a licence is represented, how entitlement is checked at pull time, or what the analytics expose. The registry is described as OCI-compatible and able to hold Docker images, Helm charts and Terraform modules, which is a broader artifact surface than the deployment side of the product covers: the agents handle Docker Compose, Docker Swarm and Helm applications, according to the repository description. So you can store a Terraform module in the Distr registry without any agent applying it for you. That gap is easy to miss when reading the feature bullets.
A second thing to verify before relying on licence management: whether it is enforced at the registry, in the agent, or purely as a presentation layer in the portal. The README does not say, and the answer changes your threat model considerably.
Where Distr is the wrong tool
Three cases stand out from the material itself.
First, if you only deploy into infrastructure you control, the Hub, PostgreSQL, Loki, object storage and registry are five components you now operate in order to do something your existing pipeline already does. The architecture diagram is a fair picture of the operational surface, and none of it is free to run.
Second, if your customers will not run an agent, you are left with the OCI client path. You keep artifact distribution and access control, and you give up deployment automation, log and metric collection, and remote troubleshooting, which the README lists as agent capabilities. For a fleet of edge devices where you need to see what happened after a failed update, that is a significant loss.
Third, the integration story is narrow. The SDK is JavaScript only. The GitHub Action at github.com/distr-sh/distr-create-version-action automates artifact version creation in CI, and the REST API covers deployments, artifacts, agents and licences, but there is no documented SDK for Go, Python or Java. A team whose release tooling is written in Go, which is the language the Hub itself is written in, would still be writing HTTP calls by hand.
There is also a versioning consideration. The recent releases listed are 3.5.1, 3.5.0 and 3.4.2, with 3.5.1 landing one day after 3.5.0. Frequent patch releases are normal for active projects, but they mean you should pin chart and image versions rather than track latest, and read the release notes before upgrading a Hub that customer agents are connected to.
How this differs from a GitOps controller
The closest familiar pattern is a GitOps controller such as Argo CD or Flux, and the difference is not cosmetic. A GitOps controller reconciles a cluster toward a desired state stored in a Git repository that both you and the customer can read. It assumes the customer is willing to run the controller, grant it cluster access, and treat a Git repo as the source of truth. It also assumes the customer's cluster is Kubernetes.
Distr inverts several of those assumptions. The desired state lives in the Hub's PostgreSQL, not in a repository the customer controls. The agent is optional and the customer may instead be a plain OCI client. And the deployment targets include Docker Compose and Docker Swarm, not only Helm, which matters for the long tail of customers running a single VM or a small Swarm cluster. What you give up in exchange is the auditability and self-service that come from a Git repository the customer can inspect. With Distr, the customer's view of what is deployed comes from your portal, not from their own Git history.
If your customers are Kubernetes-native and already run Argo CD, adding Distr means two systems claiming authority over the same workloads. Pick one.
Maintenance cost and what the Apache-2.0 licence does and does not cover
The repository is licensed under Apache License 2.0, and the README links to a pricing page for a hosted version and Enterprise plans. That combination is common and worth stating plainly: the licence covers the code in this repository, and the README does not enumerate which features sit behind the paid tiers. If your evaluation depends on a specific capability, confirm whether it is in the Apache-2.0 build before you build a process around it. Nothing here is legal advice; read the LICENSE file and the pricing page yourself.
On ongoing cost, the architecture tells you what you are signing up to operate. PostgreSQL holds state, so it needs backups you have tested. Loki accumulates logs from customer environments, which grows with the number of agents and the verbosity of what they ship. The OCI registry writes to object storage, which grows with every artifact version you publish. Upgrades follow the chart and image tags you pin. Building from source is possible and the README recommends mise, with tasks such as mise run build:hub and mise run "docker-build:**", but for most teams the chart is the cheaper path.
The honest summary is that Distr removes the per-customer scripting you would otherwise write, and replaces it with a control plane plus a database, a log store and a registry that you now own. That trade is worth making when the number of self-managed customers is large enough that per-customer scripts have become the bottleneck. Below that threshold, the operational surface is the larger cost.
Editorial conclusion
Adopt Distr if you sell software that runs inside customer infrastructure and you currently ship it over email, shared drives or a hand-rolled script per customer. Do not adopt it if your delivery target is a single cloud you control, or if you need an SDK in a language other than JavaScript today. Before committing, verify three things in your own environment: that the Hub's PostgreSQL, Loki and object storage dependencies fit your operations budget, that your packaging format is one of the three the agents handle, and whether the Apache-2.0 core plus the paid hosted and Enterprise plans cover the features you actually need.
Community notes