Meteroid: self-hosted pricing and billing for usage-based SaaS

What Meteroid solves, and for whom

The README frames the problem narrowly: traditional billing systems struggle once a company moves to usage-based pricing or product-led growth, and the gap between what a customer actually consumed and what they were invoiced is where errors appear. Meteroid's stated goal is to close that gap by collecting usage and interaction data through an API, running it through a billing engine that applies custom pricing models, and producing invoices from the result.

The README names three audiences. Engineering teams that have already built and maintained a billing system themselves. Product-led teams that want usage-based or hybrid pricing without building the infrastructure. Sales-led teams that need quote-to-cash automation. Those are different jobs, and the repository reflects that: the workspace contains a CPQ module for quotes alongside the metering and invoicing crates, so the project is not only a meter.

One thing worth flagging early: the README's own badge reads status: experimental, and the newest release is v1.0.0-rc7. Treat the audience description as intent, not as a statement about production readiness.

The two-service split: metering in Rust, billing in Postgres

The architecture is visible in Cargo.toml. The workspace is organised into modules/meteroid for the billing side and modules/metering for the metering side, with separate gRPC crates for each (meteroid-grpc and metering-grpc). Shared crates cover Kafka, gRPC plumbing, configuration, logging, a distributed lock, and an event bus.

The data path implied by .env.example runs through Kafka and ClickHouse. Usage events land on a Kafka topic named by KAFKA_RAW_TOPIC, whose example value is meteroid-events-raw. ClickHouse is configured separately for HTTP and TCP (CLICKHOUSE_HTTP_ADDRESS and CLICKHOUSE_TCP_ADDRESS), which is the shape you would expect from an analytics store holding high-volume event data. Postgres holds the billing side, configured through DATABASE_URL. Two listen addresses are exposed, one for the billing API (METEROID_API_LISTEN_ADDRESS, example 0.0.0.0:50061) and one for metering (METERING_API_LISTEN_ADDRESS, example 0.0.0.0:50062), plus a REST API on METEROID_REST_API_LISTEN_ADDRESS (example 0.0.0.0:8084).

The README claims metering transforms raw usage events into billable metrics "in real time, without pre-aggregation", powered by Rust for high-throughput ingestion. That is a design claim about where aggregation happens, not a benchmark, and the README does not publish throughput numbers. The practical consequence is that you are running three stateful systems, not one. The repository also lists adapters for OpenStack and Slurm, which tells you the intended ingestion sources include infrastructure and HPC workloads, not only API calls.

Installing Meteroid from source and sending a first event

The README does not put installation steps in the main file. It points to CONTRIBUTING.md for how to install Meteroid from sources, and the deployment section is truncated mid-sentence after "We provide". So the authoritative install path is the contributing guide, not the README.

What the repository does give you is the configuration surface. Copy .env.example to .env and fill in the platform secrets. Three of them are required before anything starts: JWT_SECRET, INTERNAL_API_SECRET, and SECRETS_CRYPT_KEY, which the file notes must be 32 characters long.

cp .env.example .env

The database, Kafka and ClickHouse settings in that file are the defaults you will need to match or override:

DATABASE_URL=postgres://${DATABASE_USER}:${DATABASE_PASSWORD}@localhost:5432/${DATABASE_NAME}?sslmode=disable
KAFKA_BOOTSTRAP_SERVERS=127.0.0.1:9092
KAFKA_RAW_TOPIC=meteroid-events-raw
CLICKHOUSE_HTTP_ADDRESS=http://127.0.0.1:8123
CLICKHOUSE_TCP_ADDRESS=127.0.0.1:9000

Object storage is configurable in two modes. The development default writes to the filesystem, and the commented block switches to S3, which the file says works with MinIO and AWS S3:

OBJECT_STORE_URI=file:///tmp/meteroid/object-store
# OBJECT_STORE_URI=s3://meteroid
# AWS_ENDPOINT=http://localhost:9002

For a first real use, the repository ships three sample files at the top level: sample_customers.csv, sample_events.csv and sample_subscriptions.csv. They are the closest thing to a guided first run available, and they map onto the three things you would want to prove before trusting the system: that a customer exists, that usage events flow through metering, and that a subscription produces the invoice you expect. The README does not document the exact commands that load these files, so check CONTRIBUTING.md and the docs site for the current invocation rather than guessing at flags.

Where Meteroid is the wrong tool

The status badge is the first limitation, and it is the project's own. A release candidate labelled experimental is not something to put under a revenue-critical invoice run without a fallback. The release history supports that reading: v1.0.0-rc5, rc6 and rc7 landed between June and August 2026, which is a fast-moving pre-1.0 line.

Operationally, the dependency set is the second limitation. Postgres for billing state, Kafka for event transport, ClickHouse for the event store, and an object store. That is a real infrastructure commitment. A team that just wants to charge a flat monthly fee has no reason to run a Kafka cluster to get there, and the README's own deployment section suggests Meteroid Cloud for people who are only testing, which is an admission that self-hosting is not the light path.

Third, features listed in the README are not all shipped. The Insights and Reporting entry carries the note "(Coming soon)", so revenue analytics is not something you can evaluate today. Treat the feature list as a roadmap with a few items already delivered, not as a checklist of what runs when you install it. Finally, the README is silent on rollback and on upgrade procedures between release candidates, and it does not document data migration between versions. If you are deciding based on operational safety, that silence matters more than any feature bullet.

Meteroid compared with Stripe Billing as the default

The honest alternative for most teams is not another open source project. It is Stripe Billing, which the repository itself treats as part of its environment: the workspace contains a stripe-client crate, and the topics list includes stripe alongside payments. That is the key difference in approach. With Stripe Billing, the pricing model, the subscription state and the invoice live inside Stripe, and your application calls their API. You get a managed system and you accept their data model and their pricing.

Meteroid inverts that. Pricing, plans, subscriptions and invoices live in your Postgres, the raw usage events live in your ClickHouse, and Stripe becomes one integration among several, next to gocardless-client, stancer-client, hubspot-client and pennylane-client in Cargo.toml. The README describes plans as versioned, so pricing changes do not affect existing customers unless you want them to. That grandfathering behaviour is the thing a managed provider makes you work around rather than the thing it gives you.

The trade is straightforward. You gain control over the pricing model, the event data, and the versioning semantics, and you take on the operational burden of running the stack. If your pricing is a flat fee per seat, Stripe Billing is less work and the difference in approach does not buy you anything. If your pricing is hybrid, tiered, or changes per customer, the case for owning the model gets stronger.

Licence and the cost of keeping Meteroid current

The licence is AGPL-3.0-only, declared in both the repository metadata and the workspace.package section of Cargo.toml. The AGPL's distinguishing feature is the network clause: if you modify the software and let users interact with it over a network, the licence's obligations extend to that interaction. That is a different posture from a permissive licence, and it is the single fact most likely to change a build-versus-adopt decision. Whether it applies to your deployment depends on your facts, so take advice rather than reasoning from this summary.

One detail worth noting for anyone auditing dependencies: the workspace vendors a third-party crate, crates/world-tax, and the Cargo.toml comment points to the crate's own LICENSE files. Licence review of a Meteroid deployment therefore does not stop at the top-level AGPL file.

On upgrade cost, the repository supports only a limited answer. The project is pre-1.0 and releases candidates frequently, with three rc releases in roughly two months. The README does not document an upgrade path, a migration procedure, or a compatibility policy between release candidates. The toolchain is pinned, with rust-toolchain.toml at the top level and rust-version = "1.96" in the workspace, so building from source expects a matching Rust version. Budget for reading release notes between candidates, because the repository does not promise that a config or schema from one candidate carries into the next.

Editorial conclusion

Adopt Meteroid if you are running usage-based or hybrid pricing and want the metering and invoicing pipeline inside your own infrastructure, with plans versioned so a price change does not silently rewrite existing subscriptions. Do not adopt it if you need a stable 1.0 release today, if you cannot operate Postgres, Kafka and ClickHouse, or if you want a hosted service with no infrastructure of your own; the README's own status badge says experimental, and the newest release is v1.0.0-rc7. Before committing, verify three things from the repository: that the CONTRIBUTING guide's source install works on your toolchain, that your usage event volume fits the Kafka plus ClickHouse path, and that the AGPL-3.0-only licence in Cargo.toml is acceptable for how you plan to distribute anything you build on top of it.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. meteroid-oss/meteroid on GitHub
3. Project website
4. README
5. Releases