Security and access

These settings control who and what can reach your self-hosted data plane, and what they can touch. Most are optional and default to permissive behavior suitable for trusted, single-organization deployments.

Secure sensitive customer data

Braintrust’s servers and employees do not require access to your data plane for it to operate successfully. That means that you can protect it behind a firewall or VPN and physically isolate it from access. When you use the Braintrust web application, it communicates directly with the data plane (via CORS), and the data does not flow through any intermediate systems (the control plane, or otherwise) before reaching your browser. While the data plane does send metrics and status telemetry to the control plane, it does not send logs, traces, or customer data. Because of this architecture, our self-hosted customers do not generally list us as a subprocessor. Like any third-party software, it is important that you establish the appropriate controls to ensure that your deployment is secure, and Braintrust can help you do so. Ultimately, the goal of the control plane and data plane split is to provide you with the highest levels of security and compliance.

Grant browser permissions

This is a client-side step performed by end-users in their browser, not a Terraform or Helm setting. The only deployment-side control is the Data plane is on a private network toggle in organization settings.

If your data plane is deployed behind a VPN or on a private network (not accessible from the public internet), users will need to grant browser permissions to access it. When you enable the Data plane is on a private network setting in organization settings, the Braintrust UI will check for Chrome’s Local Network Access permission. When users access your Braintrust org for the first time and a private network data plane has been configured, Chrome will display a permission prompt. Users must click Allow to grant permission for the Braintrust UI to communicate with your data plane. If permissions are blocked, we will display a modal with the steps to correct the issue.

Local Network Access is a Chrome security feature that protects users from malicious websites accessing resources on their private networks. For more information, see Chrome’s Private Network Access documentation.

If you encounter connectivity issues, ensure that your browser is up to date, any corporate proxies or network policies allow browser access to the data plane, and CORS is properly configured on your data plane deployment (automatically handled by Braintrust Terraform modules).

Configure organization authorization

By default, any Braintrust organization can authenticate against your self-hosted data plane. Use the following settings to restrict access to specific organizations. You can find an organization’s ID in the Braintrust UI. See Find your organization ID.

AWS
GCP / Azure

Set allowed_org_ids to a comma-separated list of Braintrust organization UUIDs (available in Terraform module v5.8.1 or later):

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane"

  allowed_org_ids = "00000000-0000-4000-8000-000000000001,00000000-0000-4000-8000-000000000002"

  # ... other configuration ...
}

Only organizations whose IDs appear in the list can use the deployment. Leave the variable empty (the default) to impose no restriction. Organization IDs must be UUIDs, not organization names.

If braintrust_org_name is set to a specific organization name, include that organization’s ID in allowed_org_ids for forward compatibility.

These settings apply to deployments using the Helm chart (6.7.1+). Two global values control which organizations can use the deployment.global.primaryOrgName identifies the primary organization for self-hosted service-token management, which enables features such as data retention. It is required when global.orgName is empty or "*" (a wildcard that allows all organizations). For standard single-organization deployments with a specific orgName, this value is not needed.global.allowedOrgIds is an optional comma-separated list of Braintrust organization IDs (UUIDs, not org names) authorized to use this deployment. When global.orgName is a specific name, that org is implicitly included. Include its Braintrust org ID here for forward compatibility.

These two values serve different purposes. global.primaryOrgName enables service-token management for a wildcard or empty orgName. It does not restrict which organizations can authenticate. To scope access on a wildcard deployment, also set global.allowedOrgIds. Without it, any organization can authenticate.

global:
  orgName: "*"
  primaryOrgName: "your-primary-org"  # Required when orgName is "*" or empty
  allowedOrgIds: "00000000-0000-4000-8000-000000000001"  # Optional org ID allowlist

Deploying with global.orgName: "*" or an empty value without setting global.primaryOrgName (or providing PRIMARY_ORG_NAME via api.extraEnvVars) causes a Helm template validation error.

Configure URL security

Braintrust backends validate user-supplied URLs (such as webhook targets and external endpoints invoked by scorers or tools) before making outbound requests, to prevent server-side request forgery (SSRF). By default, requests that resolve to private or reserved IP ranges are allowed and logged with a warning rather than blocked. To block them, set the URL request mode to reject.

AWS
GCP / Azure

The following Terraform variables configure URL security (available in module v5.8.1 or later):

Variable	Default	Description
`unsafe_url_request_mode`	`""` (application default: `warn`)	How the backend handles requests to URLs that fail security checks. `reject` blocks, `warn` allows with a log warning, `proxy` routes through the configured outbound proxy, or `off` allows.
`url_security_dns_servers`	`""`	Comma-separated DNS resolver IPs used to validate user-supplied URLs. Set this to route validation through your VPC or corporate DNS.
`url_security_allow_cidrs`	`""`	Comma-separated CIDR ranges to allow even if private or reserved. This allowlist cannot override metadata endpoints, link-local, multicast, unspecified, or future-use ranges, which stay blocked in `reject` mode.

To block all requests to private or reserved addresses:

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane"

  unsafe_url_request_mode = "reject"

  # ... other configuration ...
}

To allow a specific internal CIDR while warning on other private ranges:

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane"

  unsafe_url_request_mode  = "warn"
  url_security_allow_cidrs = "10.0.1.0/24"

  # ... other configuration ...
}

These settings apply to deployments using the Helm chart (6.7.1+). Set the following api values in your Helm values.yaml file:

Value	Default	Description
`api.unsafeUrlRequestMode`	`""`	How to handle requests to URLs that resolve to private or reserved addresses. Leave empty to use the application default (`warn`). Set to `reject` to block, `warn` to allow with a log warning, or `off` to allow. The API and runtime fetch paths also support `proxy`, which routes the request through the configured outbound proxy. The AI Gateway supports only `reject`, `warn`, and `off`.
`api.urlSecurityDnsServers`	`""`	Comma-separated DNS resolver IP addresses used when validating user-supplied URLs. Set to your VNet or corporate DNS servers to enforce resolution through a trusted nameserver before falling back to the host resolver.
`api.urlSecurityAllowCidrs`	`""`	Comma-separated CIDR ranges that URL validation allows even if they are private or reserved. This allowlist cannot override metadata endpoints, link-local, multicast, unspecified, or future-use ranges, which stay blocked in `reject` mode.

To reject all requests to private or reserved addresses:

api:
  unsafeUrlRequestMode: "reject"

To allow specific internal CIDRs while rejecting others:

api:
  unsafeUrlRequestMode: "reject"
  urlSecurityAllowCidrs: "10.0.0.0/8"

To resolve user-supplied URLs through a trusted DNS server:

api:
  urlSecurityDnsServers: "10.0.0.53"

Setting the URL request mode to off disables all URL security checks and allows outbound requests to private and reserved IP ranges. Avoid off for internet-facing deployments.

Enable audit headers

Audit headers are a legacy feature, retained for existing integrations. They predate Braintrust’s audit logging feature, which is the recommended way to track administrative actions and data access. Audit headers are enabled per request by the API client rather than through Terraform or Helm.

When actions must be attributed to specific users or tracked for compliance, enable audit headers. These headers add metadata about the request and the resources it touched to the API response. To enable audit headers, include the x-bt-enable-audit: true header in your API request. When this header is present, the API response will include the following additional headers:

x-bt-audit-user-id: The ID of the user who made the request (based on the provided API key or impersonation).
x-bt-audit-user-email: The email of the user who made the request.
x-bt-audit-normalized-url: A normalized representation of the API endpoint path that was called. Path parameters like object IDs are replaced with placeholders (for example, /v1/project/[id]).
x-bt-audit-resources: A JSON-encoded, gzipped, and base64-encoded string containing a list of Braintrust resources (like projects, experiments, datasets, etc.) that were accessed or modified by the request. Each resource object includes its type, id, and name.

The x-bt-audit-resources header requires specific parsing due to its encoding. Here’s an example of how to parse it using the Python SDK:

import os

import braintrust
import requests

API_URL = "https://api.braintrust.dev/v1"
# Ensure BRAINTRUST_API_KEY is set in your environment.
headers = {
    "Authorization": "Bearer " + os.environ["BRAINTRUST_API_KEY"],
    "x-bt-enable-audit": "true",  # Enable audit headers
}

# Example: Create a project.
response = requests.post(f"{API_URL}/project", headers=headers, json={"name": "audit-test-project"})
response.raise_for_status()

project_data = response.json()
print(f"Project created: {project_data['name']} (ID: {project_data['id']})")

# Access and parse audit headers.
user_id = response.headers.get("x-bt-audit-user-id")
user_email = response.headers.get("x-bt-audit-user-email")
normalized_url = response.headers.get("x-bt-audit-normalized-url")
resources_header = response.headers.get("x-bt-audit-resources")

print(f"Audit User ID: {user_id}")
print(f"Audit User Email: {user_email}")
print(f"Normalized URL: {normalized_url}")

if resources_header:
    try:
        # Use the provided utility to parse the resources header.
        resources = braintrust.parse_audit_resources(resources_header)
        print("Accessed/Modified Resources:")
        for resource in resources:
            print(f"  - Type: {resource['type']}, ID: {resource['id']}, Name: {resource['name']}")
    except Exception as e:
        print(f"Error parsing resources header: {e}")
else:
    print("No resources header found.")

This feature is useful for building audit logs or understanding resource usage patterns within your applications that interact with the Braintrust API.

Enable S3 attribute-based access control

On AWS, IAM policies for the S3 buckets the module manages grant access by bucket ARN. To base access decisions on bucket tags instead, set the enable_s3_bucket_abac Terraform variable to true (available in Terraform module v5.3.0 or later). This supports tag-based governance or service control policies that gate access by resource tags.

enable_s3_bucket_abac = true

When enabled, you can reference bucket tags in IAM authorization policies, and managing those tags requires the s3:TagResource, s3:UntagResource, and s3:ListTagsForResource permissions. This variable is disabled by default.

Pod security contexts and storage limits

This section applies to GCP and Azure deployments using the Helm chart (6.2.2+).

Starting in Helm chart 6.2.2, you can harden Braintrust pods by configuring pod- and container-level security contexts, explicit ephemeral storage requests and limits, emptyDir size limits, and writable /tmp volumes for the API and all Brainstore roles (brainstore.reader, brainstore.fastreader, brainstore.writer). By default, the Braintrust manifests don’t set these fields, so configure them only if you want to enforce a stricter security posture. Some hardened clusters require these settings. They enforce admission policies, often written as Common Expression Language (CEL) constraints, that reject any workload unless its pods declare a non-root, read-only security context and bounded storage. GKE Autopilot is one such environment, so a deployment that doesn’t set these fields is blocked until you add them.

The settings in this section apply to any GCP or Azure Helm deployment. For a complete reference, see the examples/google-autopilot-cel/values.yaml example in the Helm chart, which configures them for GKE Autopilot.

Security contexts

Set a container-level securityContext on the API and each Brainstore role to enforce a read-only root filesystem, disallow privilege escalation, and drop all Linux capabilities:

api:
  securityContext:
    readOnlyRootFilesystem: true
    allowPrivilegeEscalation: false
    capabilities:
      drop:
        - ALL

brainstore:
  reader:
    securityContext:
      readOnlyRootFilesystem: true
      allowPrivilegeEscalation: false
      capabilities:
        drop:
          - ALL
  fastreader:
    securityContext:
      readOnlyRootFilesystem: true
      allowPrivilegeEscalation: false
      capabilities:
        drop:
          - ALL
  writer:
    securityContext:
      readOnlyRootFilesystem: true
      allowPrivilegeEscalation: false
      capabilities:
        drop:
          - ALL

You can also set an optional pod-level podSecurityContext (for example, api.podSecurityContext or brainstore.reader.podSecurityContext) to apply settings such as runAsNonRoot or fsGroup to the entire pod. Both contexts are omitted from the rendered manifests unless you set them.

Writable /tmp volumes

When you enable readOnlyRootFilesystem: true, the container can no longer write to its root filesystem. Enable a tmpVolume for each affected component to mount a writable emptyDir at /tmp:

api:
  tmpVolume:
    enabled: true
    sizeLimit: "1Gi"

brainstore:
  reader:
    tmpVolume:
      enabled: true
      sizeLimit: "1Gi"
  fastreader:
    tmpVolume:
      enabled: true
      sizeLimit: "1Gi"
  writer:
    tmpVolume:
      enabled: true
      sizeLimit: "1Gi"

Any component with readOnlyRootFilesystem: true must also set tmpVolume.enabled: true. Without a writable /tmp volume, processes that write temporary files fail at runtime.

Ephemeral storage and cache volume limits

Each Brainstore role accepts an ephemeralStorage budget and a volume.sizeLimit for its cache emptyDir:

brainstore:
  reader:
    ephemeralStorage:
      request: "1000Gi"
      limit: "1000Gi"
    volume:
      size: "1000Gi"
      sizeLimit: "900Gi"
    objectStoreCacheFileSize: "900Gi"

ephemeralStorage.request sets the pod-local storage budget that GKE Autopilot reserves. ephemeralStorage.limit sets the corresponding cap.
volume.sizeLimit caps the cache emptyDir. Match it to objectStoreCacheFileSize so the cache cannot exceed its allotted space.

How the ephemeral storage request is applied depends on your cloud and mode:

Deployment	Behavior
GKE Autopilot (`cloud: google`, `google.mode: autopilot`)	`ephemeralStorage.request` is applied. If unset, `volume.size` is used as the fallback request.
AWS	`ephemeralStorage.request` and `ephemeralStorage.limit` are applied when set.
GKE Standard and Azure	Ephemeral storage requests are not injected.

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Secure sensitive customer data

Grant browser permissions

Configure organization authorization

Configure URL security

Enable audit headers

Enable S3 attribute-based access control

Pod security contexts and storage limits

Security contexts

Writable /tmp volumes

Ephemeral storage and cache volume limits

​Secure sensitive customer data

​Grant browser permissions

​Configure organization authorization

​Configure URL security

​Enable audit headers

​Enable S3 attribute-based access control

​Pod security contexts and storage limits

​Security contexts

​Writable /tmp volumes

​Ephemeral storage and cache volume limits

Secure sensitive customer data

Grant browser permissions

Configure organization authorization

Configure URL security

Enable audit headers

Enable S3 attribute-based access control

Pod security contexts and storage limits

Security contexts

Writable /tmp volumes

Ephemeral storage and cache volume limits