Find the ceiling before production finds it.

Every resource is correct. The sizes never talk to each other.

Something picked those numbers: a model that has never seen your traffic, a copied module, or you at the end of a long day. Each one is defensible on its own line. The bottleneck only exists between two of them, and nothing you run reads two lines at once.

• sized too small

  03:40, the service scaled out exactly the way you told it to, and the app cannot open a connection. The database is sitting at 12% CPU. It was never CPU: 40 tasks at a pool of 20 is 800 connections into an instance class that accepts 450.

• sized too large

  A db.r5.2xlarge in front of a service that will never open more than 60 connections. It passed review because oversizing has never woken anybody up, and it bills every hour for a ceiling nobody is going to reach.

• the one that is not compute

  A /28 subnet offers 11 usable addresses and the autoscaler is authorised for 40 awsvpc tasks. Placement starts failing at 55% of that, and the error names the subnet, never the line that sized it.

1. terraform validate

   Passes. Every resource is correct in isolation.

2. terraform apply

   Succeeds. Nothing in a plan compares one size against another size.

3. traffic

   Arrives. The first size to run out decides how far the system actually scales, and you find out in production.

Infracost tells you the price. Spacelift tells you the run passed. Vantage tells you the bill went up. The ceiling is the one number none of them carry.

Four things it does that your pipeline currently does not.

• It gives you the ceiling, not the bill.

  Cost tools price what you provisioned and CI tools confirm the run passed, which leaves the limit itself unmeasured. You get the number the resource actually stops at, so you size it in a pull request instead of during an incident.

• It finds the edges Terraform never drew.

  The link that broke the fixture below is not in the dependency graph at all: it is derived from a security group ingress rule pointing at another security group. That is exactly the class of coupling a review misses, because no single file contains it.

• Every ceiling carries a source and a date.

  Each catalog entry ships with the vendor document it came from, the day it was verified and a confidence level, and a rule that cannot ground its numbers stays silent and tells you what it skipped. You can defend the number in an architecture review, and you are never arguing with a guess.

• One static binary that reports nothing about you.

  It parses on your machine, reads only an allowlist of capacity attributes, and carries one dependency that has none of its own. It drops into CI as a single line and clears a security review without an exception.

Real output, from a fixture that plans without an account.

fixtures/01-ecs-rds is real Terraform shaped like what a model returns for “give me an ECS service on Fargate with a postgres database”. The plan applies cleanly, every resource is correct in isolation, and the run below is the unedited output.

  At full scale the workloads in front of aws_db_instance.main open ~800
  connections against a ceiling of ~450. Saturation lands at 56% of the scale
  this plan already authorises.

    - aws_ecs_service.api scales to 40 tasks (max_capacity of
      aws_appautoscaling_target.api) x 20 connections per task (DB_POOL_SIZE=20
      in aws_ecs_task_definition.api) = 800 connections
    - aws_db_instance.main (db.t3.medium, postgres) accepts ~450 connections by
      default [LEAST({DBInstanceClassMemory/9531392}, 5000)]

  confidence: high  |  source: docs.aws.amazon.com/AmazonRDS/.../CHAP_Limits.html

  aws_subnet.private_a (10.0.1.0/28) offers 11 usable addresses and the
  workloads placed in it need ~20 at full scale. Task placement starts failing
  at 55% of the authorised scale.

Two independent ceilings, two different percentages, one plan that passes every check it is given.

Three steps, and you already run two of them.

There is nothing to install in the cluster, nothing to grant and nothing to sign up for. headroom reads the JSON that terraform already knows how to print, so the first real answer is about a minute away.

1. 01

   Install the binary

   One line, or a download you verify against the published checksums. It is a single static binary, so there is no runtime to install first and nothing to configure before the first run.

   $curl -fsSL https://headroomcli.com/install.sh | sh
2. 02

   Print the plan you already make

   terraform plan then terraform show -json, the two commands your pipeline runs anyway. The JSON stays on your disk: headroom reads the file, it does not connect to your account or to your cloud.

   $terraform plan -out=tfplan $terraform show -json tfplan > plan.json
3. 03

   Run it, and read the ceilings

   headroom analyze plan.json prints every resource that runs out first, with the number, the source behind it and the percentage of your authorised scale. Add --fail-on critical and the same command becomes the whole CI gate.

   $headroom analyze plan.json

Flags worth knowing

--json

Findings as JSON, for a CI gate or a dashboard you already own.

--dry-run

Print the exact redacted payload that would be uploaded, and upload nothing.

--fail-on critical

Exit 1 on critical, or on warning and worse. That is the whole CI integration.

--pool-size N

Connections per task to assume when the task definition does not declare one.

--warn-at R

Utilization ratio that triggers a warning. Default 0.8.

--salt S

Per organization salt used to hash resource addresses.

--no-update-check

Silence the once a day check for a newer release. HEADROOM_NO_UPDATE_CHECK=1 does the same.

A headroom.yaml at the root of the repository is picked up automatically: tune a rule, state a fact about your account that no plan can state, or silence a finding with a mandatory reason and an expiry date, so the finding comes back on the day the reason ran out.

Twenty rules, three clouds, every one of them grounded.

Provider coverage is uneven on purpose. Each cloud ships the rules whose ceilings are actually published, and a rule with no source behind it does not ship at all.

Your plan file never leaves your machine.

Extraction is by allowlist, never denylist.

Per resource type there is a closed list of the attributes that matter for capacity. Anything not on that list is never read, so it cannot leak. A denylist leaks the first time a provider adds an attribute nobody anticipated.

• The CLI parses locally. The plan file is read on your disk and stays there.
• Resource addresses are hashed with a per organization salt. Real names exist only on your machine, and the local report reattaches them.
• Finding text is not uploaded either. A rule id, a severity and the bare numbers travel, and the sentence is rebuilt on the other side.
• headroom analyze --dry-run prints the exact payload, and it is the only thing that ever carries your data off the machine.
• Two things open a socket. The upload you ask for, and a once a day check for a newer release that sends no query string, no identifier and no version, and stops with --no-update-check.

module github.com/headroom-project/headroom

go 1.26.6

require gopkg.in/yaml.v3 v3.0.1

Parsing a plan file is a weekend. The catalog is the part that takes years.

What nobody has is the ceiling table: given a resource in a given configuration, what its real limit is. That number is almost never in the Terraform. db.t3.medium does not say “450 connections” anywhere in the state. It comes from a parameter group formula over the instance class memory, and the formula differs between MySQL, MariaDB and PostgreSQL.

{
  "ceiling": "max_connections",
  "formula": "LEAST({DBInstanceClassMemory/9531392}, 5000)",
  "source": "https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Limits.html",
  "verified_at": "2026-08-14",
  "confidence": "high"
}

Every entry carries source, verified_at and confidence. No entry ships without them. It is plain JSON on purpose: the knowledge has to survive any rewrite of the code around it.

Every number in the catalog was verified against primary vendor documentation on 2026-08-14. That pass found and fixed two of our own wrong ceilings. The discipline is the product.

Free is the whole CLI. Paid is only the part that needs a server.

One repository fits in a binary. Joining ten of them needs a server, an account, an identity and history. What is paid is exactly what needs a server, not a good feature locked artificially.

• Free

  $0

  Open source, on GitHub today

  • The full CLI: 20 rules across AWS, Azure and Google Cloud, with the catalog embedded in the binary
  • headroom.yaml for tuning, exceptions and your own policy rules
  • JSON output, --dry-run, and a CI gate with --fail-on
  • Apache 2.0, patent grant included, no usage limit and no account
  Download the open source CLI

• for a team

  Premium

  $10per month

  Up to 3 seats and 1 organisation

  • Everything in Free, for every member of the team
  • Web dashboard with history and trend, so a ceiling moving toward you is visible before it arrives
  • Automatic pull request comments through the GitHub App
  • Findings kept per organisation, with resource names hashed by your own salt
  Coming, not available yet

  No lock in

• Enterprise

  On request

  More seats, more than one organisation

  • Everything in Premium, without the seat and organisation limits
  • Cross repository macro analysis, which is where a shared ceiling actually shows up
  • Continuous AWS, Azure and Google Cloud collectors
  • A say in which rules get built next, and in the order they arrive
  Talk to us

  No lock in

Only the Free column exists today. Premium and Enterprise are being built, the price is what they will launch at, and nothing on this page takes a payment yet.

Install

A single static binary. Nothing to configure before the first run.

Language

Go, one static binary

Dependencies

one, and it has none of its own gopkg.in/yaml.v3

License

Apache 2.0, patent grant included

Clouds

AWS, Azure and Google Cloud

$ curl -fsSL https://headroomcli.com/install.sh | sh

Or take the path you can verify

go install github.com/headroom-project/headroom@latest

# or download and verify
curl -LO https://github.com/headroom-project/headroom/releases/latest/download/headroom_linux_amd64.tar.gz
curl -LO https://github.com/headroom-project/headroom/releases/latest/download/checksums.txt
sha256sum -c checksums.txt

Direct downloads

• Linuxamd64headroom_linux_amd64.tar.gz
• Linuxarm64headroom_linux_arm64.tar.gz
• macOSarm64headroom_darwin_arm64.tar.gz
• macOSamd64headroom_darwin_amd64.tar.gz
• Windowsamd64headroom_windows_amd64.zip

Every release ships checksums.txt next to the archives. Verify before you run it, the same way you would want your own users to.