Cloud Carbon Footprint: turning cloud billing and usage data into an emissions estimate

What the tool actually measures: an estimate from usage, not a reading from the grid

The README states the scope in one sentence: the application estimates the energy use in kilowatt hours and the carbon emissions in metric tons of CO2e of public cloud provider utilization. Two words in that sentence define the limits of the tool. It estimates, so the output is modelled rather than metered, and it covers public cloud, so on-premises hardware is handled separately. The project is hosted under a Thoughtworks copyright and the documentation site carries a Methodology page that explains the calculations and constants behind the estimates, and that page is the honest place to start, because the quality of the answer depends entirely on the constants. The user is a team with cloud accounts that wants a figure they can put in a report or compare month over month, not an organisation buying certified offsets.

Three surfaces over one core: the CLI, the API and the web client

The Getting Started section says the core logic is exposed through two applications, a CLI and a website, and that the website splits into an API and a client. In the repository that is packages/cli/, packages/api/ and packages/client/, and the root package.json wires them together as yarn workspaces with lerna handling the orchestration. The scripts section shows what each surface is for, and the names are informative. There is a start script that runs the client and the API concurrently, a start-cli script for the CLI alone, a start-with-mock-data script that runs the client against mock data rather than a live API, and a guided-install script that runs an install through the CLI. The last one matters for evaluation, because it is a path to a working setup without hand wiring a cloud account, and the Getting Started page on the documentation site is where the full instructions live.

Cloud data comes in through AWS, GCP and Azure credentials, not a manual export

The docker-compose.yml at the root of the repository shows how the data actually enters the system, and it is a long list of cloud secrets. The API service declares secrets for the AWS side including AWS_TARGET_ACCOUNT_ROLE_NAME, the Athena database name, table, region and query result location, plus the billing account id and name, and for GCP the BigQuery table, billing project id and project name, and for Azure the client id, client secret and tenant id. The AWS_USE_BILLING_DATA and GCP_USE_BILLING_DATA environment variables are set to true, which selects the cost allocation path over the resource usage path, and the CACHE_MODE variable is set to LOCAL, with a comment explaining that setting it to MONGODB selects the MongoDB cache instead, backed by the MONGODB_URI and MONGODB_CREDENTIALS secrets. The credentials themselves are mounted from the host, with the AWS credentials file and the GCP service account key file bound into the container. There is also an optional Electricity Maps API token, commented out, which is the hook for a live grid carbon intensity signal.

The CLI is where the data preparation happens, and it has dedicated commands for it

Beyond starting the tool, the CLI exposes several data preparation commands, and they show the shape of the pipeline. There is a create-lookup-table command and a create-azure-lookup command, which are about building the tables that map provider resources to their energy and carbon attributes, and an estimate-on-premise-data command, which is the on-premises path the README otherwise does not spell out. A seed-cache-file command exists to prime the cache, and a guided-install command drives the setup interactively. The presence of a lookup table as a first class artefact is the point worth noting: the mapping from a virtual machine or a database instance to its power draw is data, and a data set you can inspect and argue about, not a constant buried in code. There is also a footprint-test.http file at the repository root, which is a request collection for exercising the API endpoints by hand.

Deployment options are wide: Docker Compose, Terraform, CloudFormation, Helm and App Engine

The repository carries five deployment surfaces, and that spread is itself a signal about the audience. There is docker-compose.yml and docker-compose.local.yml for local and single host use, a docker/ directory for image builds, a terraform/ directory and a cloudformation/ directory for infrastructure as code on the two major clouds, an appengine/ directory for Google App Engine, and a helm/ directory for Kubernetes deployment. The Helm chart and the Terraform and CloudFormation templates are the ones that matter for an organisation already running cloud infrastructure, since the API needs credentials, secrets and a cache database, and none of that is a single container. The helm/ directory in particular suggests the intended production shape is a small set of pods with secrets mounted, which matches how the Compose file declares them.

Release and upkeep: a 2026 tag, a trunk branch, and no recent activity

The default branch is trunk, and the release list shows a rolling latest tag dated 2026-04-23 along with dated release tags from 2024-05-11 and 2024-02-11. The last push to the repository was on 2026-04-23, which is the most recent recorded activity, and the honest statement is that date of the last push. In practice the newest release and the newest code are the same artefact, which is at least unambiguous for anyone pinning a version. The repository structure shows a considered development process around that code: an.adr/ directory for architecture decision records alongside.adr-dir, a.changeset/ directory for version changes, husky hooks, a.prettierrc.json, a SonarQube configuration, CircleCI configuration alongside GitHub workflows, and a Jest base config. The root package.json requires Node 24.0.0 or newer, so the runtime floor is recent.

Licence, community signals and what is missing from the README

The licence is Apache 2.0, with the copyright held by Thoughtworks Inc. for 2021 and the licence text in the LICENSE file alongside a NOTICE file, which is the pattern to check when you redistribute anything derived from it. On community, the README points at an ADOPTERS.md file where users are asked to record how they are running the tool, which provider mix they use and the size of their organisation, and at a feedback form, plus a Google group for questions. The project also asks contributors to read a contributing page and a code of conduct, and the roadmap lives on a project board with issues tracked on GitHub. What the README does not contain is any worked example of a usage record, a sample output, or the list of supported resources, so a reader who wants to know how precise the numbers are has to go to the Methodology page and the getting started guide before deciding.

Editorial conclusion

Cloud Carbon Footprint suits an engineering team that wants a repeatable, methodology-based estimate of the emissions implied by its cloud accounts, and that can live with a number derived from published constants rather than from a measured grid signal. It is the wrong tool if you need metered, real time emissions data or an audit grade figure, because the output is an estimate produced from usage data and a set of constants, and the README points to a Methodology page for exactly those calculations. Before adopting it, read the Methodology page and decide whether its constants match your geography and provider mix, check the Getting Started page for the guided install path in the CLI, and note that the last push to the repository was on 2026-04-23, so the newest release and the newest code are the same artefact.

Frequently asked questions

Official sources

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