Implementing carbon.txt
For Digital Service Providers

As a provider of managed digital services, you can implement carbon.txt to demonstrate that the infrastructure you manage or use to provide your service runs on green energy. It also allows you to pass this on to your customers, allowing any downstream services or websites using your services to make the same claims, with a clear chain of attribution.

Getting started

Follow the steps below to create an implement a carbon.txt file for your service.

Register with the Green Web Foundation

As a digital service provider, you should first get verified by the Green Web Foundation, and provide evidence of your green claims.
Create a carbon.txt file for your organisation

Create a carbon.txt file for your organisation. There is a guide to the expected syntax below.

Use the carbon.txt builder

Note

You only need one carbon.txt file for your organisation.

To link multiple domains to a single organisation, refer to the linking green claims to multiple domains section below.
Upload your carbon.txt file to your servers.

For example: https://www.my-org.com/carbon.txt

We default to checking for a file located at the root of your domain /carbon.txt.
Share the URL of the carbon.txt file with Green Web Foundation

The Green Web Foundation has an API for registering where to check for carbon.txt file for a given domain. You can do this using the form below.

Your carbon.txt URL
Link other domains to your green claims if they are using infrastructure you control

If you offer managed hosted services to other organisations, once your first link is established there is an automated process for listing future domains so they show up as green too, with attribution to you. See domain hashes below for more.

Carbon.txt syntax

Carbon.txt files are written in TOML.

[upstream]	
# An array of providers mycompany.com is using to deliver our service
providers = [
	{ domain = "cloud.google.com", service = "shared-hosting" },
	{ domain = "aws.amazon.com", service = "cdn" }
]

[org]
# Optional.
# An array of documents that point to evidence of green claims made by mycompany.com.
credentials = [
	{ domain = "mycompany.com", doctype = "webpage", url = "https://mycompany.com/sustainability" },
	{ domain = "mycompany.com", doctype = "annual-report", url = "https://mycompany.com/carbon-emissions-2022.pdf" }
]

An example of what a carbon.txt file might look like for a digital service provider or self-hosted site.

Linking green claims to multiple domains

It's fairly common that a digital service provider might own and provide services through multiple domains. They might also have multiple products, or provide hosted services for a number of users all who have their own domains.

In this case, you can maintain a single carbon.txt file at one domain (e.g. https://my-org.com/carbon.txt) and refer other domains to that single source of truth.

There are two supported ways to do this:

Using DNS TXT records, which contain the specific URL pointing to the carbon.txt file to read.
Using a dedicated HTTP Via Header, again containing a URL for the carbon.txt file to read.

Choosing the right option for your organisation

Using DNS TXT records

Using DNS TXT records is intended for organisations who are able to add DNS records to both their own domain, as well as the domain they want to show up as green. If you own both domains, this option is for you.

Guide: How to link multiple domains using DNS TXT records

Using HTTP Via Header

Using a HTTP Via Header is intended for organisations who are not able to add DNS records for the domain they want to show up as green, but do accept HTTP requests for the domain, and serve responses for it. If you operate a CDN, a managed Wordpress service, or a general Platform-As-A-Service (PaaS) offering, this is usually better suited for your use case.

This option also allows you to "pass down" green claims to customer who use your service.

Guide: How to link multiple domains using HTTP VIA HEADER

Implementing carbon.txt For Digital Service Providers

Getting started

Register with the Green Web Foundation

Create a carbon.txt file for your organisation

Upload your carbon.txt file to your servers.