Skip to main content
These settings control how traffic reaches your self-hosted data plane, where clients point, and how connections behave behind load balancers and proxies.

​
Customize the webapp URL

The SDKs guide users to https://www.braintrust.dev (or the BRAINTRUST_APP_URL variable) to view their experiments. In some advanced configurations, you can reverse proxy traffic to the BRAINTRUST_APP_URL from the SDKs while pointing users to a different URL. To do this, you can set the BRAINTRUST_APP_PUBLIC_URL environment variable to the URL of your webapp. By default, this variable is set to the value of BRAINTRUST_APP_URL, but you can customize it as you wish. This variable is only used to display information, so even its destination does not need to be accessible from the SDK.

​
Constrain SDKs to the data plane

If you’re self-hosting the data plane, you can also constrain the SDKs to only communicate with your data plane. Normally, they communicate with the control plane to:
  • Get your data plane’s URL
  • Register and retrieve metadata (e.g. about experiments)
  • Print URLs to the webapp
The data plane can proxy the endpoints that the SDKs use to communicate with the control plane, allowing your SDKs to only communicate with the data plane directly. Set the BRAINTRUST_APP_URL environment variable to the URL of your data plane and BRAINTRUST_APP_PUBLIC_URL to “https://www.braintrust.dev” (or the URL of your webapp).

​
Restrict URLs

To restrict the URLs that the SDKs or API server can communicate with, include the following URLs:

​
Configure rate limits

By default, the Braintrust API server imposes rate limits against any external domains it reaches out to, such as the BRAINTRUST_APP_URL. The purpose of rate-limiting is to prevent unintentionally overloading any external domains, which may block the API server IP in response. By default, the rate limit is 100 requests per minute per user auth token. The API server exposes the following variables to configure the rate limits:
  • OUTBOUND_RATE_LIMIT_MAX_REQUESTS: Configure the number of requests per time window. This can be set to 0 to disable rate limiting.
  • OUTBOUND_RATE_LIMIT_WINDOW_MINUTES: Configure the time window in minutes before the rate limit resets.

​
Configure HTTP keep-alive timeout

When the API server runs behind a load balancer, you may need to configure the HTTP keep-alive timeout to prevent connection resets. Load balancers typically have an idle timeout for connections, and if the API server’s keep-alive timeout is shorter than the load balancer’s timeout, the API server closes the connection while the load balancer still considers it open. When the load balancer tries to reuse that backend connection, it encounters a closed socket, resulting in connection reset errors and 502 responses. The API server exposes the following environment variable to configure the keep-alive timeout:
  • TS_API_KEEP_ALIVE_TIMEOUT_SECONDS: The HTTP keep-alive timeout in seconds. Default: 65
The default value of 65 seconds is designed to work with most load balancers, including AWS Application Load Balancer (which has a default idle timeout of 60 seconds). However, if your load balancer has a longer idle timeout, you should set this value to match or exceed your load balancer’s timeout. For example, if you have an AWS ALB configured with a 300-second idle timeout, set:

​
Configure CloudFront origin timeout

On AWS, requests are served through CloudFront, which closes a connection and returns 504 Gateway Timeout if the origin takes too long to respond. Long-running scorers or tools invoked through /function/invoke can exceed the default 60-second origin read timeout. Raise it with the cloudfront_origin_read_timeout Terraform variable (available in Terraform module v5.3.0 or later):
The value must be between 1 and 180 seconds. CloudFront caps the origin read timeout at 180 seconds, and values above 60 seconds can require an AWS Support request to raise the account quota.

​
Configure API ALB HTTPS

On AWS with the ECS API, an internal Application Load Balancer (ALB) fronts the API services. By default, the ALB serves plain HTTP on port 80 using its AWS-assigned DNS name. To serve HTTPS on a custom domain instead, set both braintrust_api_alb_certificate_arn and braintrust_api_alb_custom_domain (available in Terraform module v6.0.0 or later):
When both are set, the ALB serves HTTPS on port 443, plain HTTP is disabled, and all API URLs use https://<braintrust_api_alb_custom_domain>. The certificate must cover the custom domain, and the domain must resolve to the ALB.
These two variables must both be set or both be null. Setting only one fails at plan time.

​
VPC connectivity

On AWS, to connect Braintrust’s VPC to other internal resources (like an LLM gateway), use one of the following approaches:
  • Create a VPC Endpoint Service for your internal resource, then create a VPC Interface Endpoint inside the Braintrust “Quarantine” VPC.
  • Set up VPC peering with the Braintrust “Quarantine” VPC.