Manage Braintrust with Terraform

As more teams in your organization begin to build agents, it’s important for each of them to have the right projects, permissions, and credentials. You can now do this in a consistent way with the Braintrust Terraform provider.

Standardize setup across teams

Terraform allows you to define projects, groups, roles, and service accounts as code alongside the infrastructure that runs your agents. The configuration is reusable, so your platform team can define a shared setup once and take advantage of it when another team joins or a new environment is needed. You can adjust permissions for each team while keeping the same approach to setup.

You can also review changes before they take effect through your existing version control process, including who changed the configuration and why. Run terraform plan to inspect the proposed resource changes before applying them.

The provider supports:

• Groups, roles, ACLs, service accounts, and service tokens for access control.
• Projects, project groups, dataset containers, score definitions, and tags for project setup.
• AI secrets, environment variables, and automations for shared configuration.

Terraform is most useful for shared settings that change relatively infrequently. You can continue managing dataset contents, logs, and experiments through your application code. Prompts and functions released with your application can stay in those workflows too.

Getting started

First, create a Braintrust organization and a service token, which gives Terraform credentials to connect to Braintrust. Then, set the BRAINTRUST_API_KEY environment variable to that token.

Your Terraform configuration identifies the Braintrust provider and describes the resources you want to create. For example, you could define a project named support-agent for evaluating and observing your support agent. This configuration uses Terraform version 1.11.1 or later and returns the project’s ID so you can reference it elsewhere:

terraform {
  required_version = ">= 1.11.1"

  required_providers {
    braintrust = {
      source = "braintrustdata/braintrust"
    }
  }
}

provider "braintrust" {}

resource "braintrust_project" "support" {
  name        = "support-agent"
  description = "Evaluation and observability for our support agent"
}

output "project_id" {
  value = braintrust_project.support.id
}

Run terraform init to install the provider, terraform plan to review the changes, and terraform apply to create the project.

For larger configurations, the repository includes examples covering multi-team access control and CI pipelines.

Using Terraform with an existing organization

You can bring existing Braintrust organizations under Terraform management. The braintrust-terraforming command-line interface (CLI) exports the org’s resources as Terraform configuration and import blocks.

Follow the installation instructions, then run the command below.

braintrust-terraforming genimport \
  --resource-types all \
  -o mybraintrustorg.tf

Review the generated configuration and keep the resources you want Terraform to manage. Each resource has a matching import instruction. If you remove a resource from the configuration, remove its import instruction as well. Run terraform init, then terraform plan to inspect the planned imports and any other changes. Once you’ve reviewed the plan, run terraform apply to import the resources into Terraform state without recreating them.

How the provider works

The provider communicates with Braintrust through the Go SDK. That SDK includes code generated from the Braintrust API specification, which describes how to send requests to Braintrust. Braintrust also generates API clients for Python, Java, and .NET from the same specification.

The provider translates your Terraform configuration into those requests. It also reads the current settings from Braintrust so Terraform can track the resources it manages and handle updates and deletions.

See the Terraform provider guide for setup instructions and examples. The provider is available on the Terraform Registry and the OpenTofu Registry, with source code on GitHub.

You can use Terraform to manage projects and access controls across your teams. Sign up for free to create an organization, or book a demo to plan a rollout across your organization.