> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up BYOC on AWS

> Prepare your AWS account for BYOC so Braintrust can deploy and operate your data plane.

To set up BYOC on AWS, you apply a CloudFormation bootstrap and security controls in a dedicated account. Braintrust then deploys and operates the data plane. See [Bring your own cloud (BYOC)](https://docs.braintrust.dev/admin/deployment/byoc.md) for how BYOC works and who manages what.

> [!WARNING]
>
> The BYOC [private preview](https://docs.braintrust.dev/feature-lifecycle.md) is available on AWS to a limited set of customers on an Enterprise plan. Behavior can change during the preview. [Contact Braintrust](https://braintrust.dev/contact) to request access.
>
> For existing AWS and Google Cloud deployments, see [BYOC for existing deployments](https://docs.braintrust.dev/admin/deployment/byoc/v1).

## Before you begin

Prepare an AWS account that meets these requirements:

* **Dedicated account.** The account must be dedicated to infrastructure that Braintrust manages. It can host more than one Braintrust data plane.
* **AWS Organizations member account.** The account must be a member account in an AWS Organization with service control policies (SCPs) enabled. It can't be the organization's management account.
* **S3 Block Public Access.** Turn on all four account-level **Block all public access** settings before you apply the [required SCPs](https://docs.braintrust.dev/admin/deployment/byoc/aws-security.md#bootstrap-security-controls).

## 1. Agree on the deployment design

Agree with Braintrust on the following for each environment:

* AWS account, Region, and capacity.
* Network, endpoint, and security requirements.
* Logging, security monitoring (SIEM), and contacts.

A bootstrap covers one AWS Region in the `aws` partition. Deploying in another Region requires a separate bootstrap or corresponding policy scope.

For design and security review, see [what runs in your account](#what-runs-in-your-account), [bootstrap resources](#2-prepare-and-review-the-bootstrap), and [AWS access and security](https://docs.braintrust.dev/admin/deployment/byoc/aws-security.md).

## 2. Prepare and review the bootstrap

The bootstrap is a CloudFormation stack that you apply with your own AWS credentials. Braintrust never receives or forwards your credentials, and the bootstrap doesn't install a persistent agent in your account.

One bootstrap can serve several data planes in the same account and Region. Each data plane has separate Terraform state and operation records.

**1. Prepare the license secret**

Braintrust helps set up your organization and provides the Brainstore license key.

Store the Brainstore license key in AWS Secrets Manager:

* Use the agreed account and Region.
* Encrypt it with the default AWS managed key (`aws/secretsmanager`). Customer managed keys aren't supported for this secret.
* Provide the secret ARN, not the key value.

Deployment automation has permission to read the license secret when needed.

**2. Review the package**

Braintrust sends a one-time package containing:

* The CloudFormation template.
* `parameters.json`, with a unique External ID that you never return to Braintrust.
* `README.md`, with commands for your account, Region, and stack.

Ask your account representative for the matching security-review package and policy revision.

**3. Review resources and permissions**

Before applying the bootstrap, review the template, every IAM policy, and the [role capabilities](https://docs.braintrust.dev/admin/deployment/byoc/aws-security.md#roles-and-access) with your security team.

All bootstrap IAM resources use the protected `/braintrust-byoc/` IAM path and end with your bootstrap name. Replace `<BOOTSTRAP_NAME>` with that name. The IAM path is part of the ARN, not the resource name.

* **Roles:** `BraintrustDeploymentRole-<BOOTSTRAP_NAME>`, `BraintrustObserverRole-<BOOTSTRAP_NAME>`, and `BraintrustDiagnosticsRole-<BOOTSTRAP_NAME>`. See [Roles and access](https://docs.braintrust.dev/admin/deployment/byoc/aws-security.md#roles-and-access).
* **Policies:** Managed policies for those roles and `BraintrustRuntimeBoundary-<BOOTSTRAP_NAME>`, a permissions boundary that caps every workload IAM role the deployment creates.
* **Storage:** Separate S3 buckets for Terraform state and operation records. Both use versioning and server-side encryption with S3 managed keys (SSE-S3), the only encryption the bootstrap supports for these buckets. Both are retained if the stack is deleted.
* **Diagnostics logging:** A Session Manager document and a CloudWatch log group, `/braintrust-byoc/<bootstrap-name>/diagnostics`, that record [Diagnostics](https://docs.braintrust.dev/admin/deployment/byoc/aws-security.md#temporary-diagnostics-access) sessions.

Braintrust reserves a name prefix for data-plane resources, such as `bt-a-`. The prefix must be 2 to 8 characters and end in a hyphen. Each deployment name starts with that prefix and is at most 18 characters.

**4. Add the license secret ARN**

In `parameters.json`, set `BrainstoreLicenseSecretArn` to the ARN of your license secret. Don't change the External ID.

## 3. Apply the bootstrap

Create the reviewed bootstrap stack, apply the required guardrails, and send Braintrust the outputs.

**1. Create the stack**

Confirm that your AWS CLI identity and Region match the target account, then create the stack as described in the package `README.md`. The stack creates named IAM resources, so it requires `CAPABILITY_NAMED_IAM`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
aws sts get-caller-identity
aws cloudformation create-stack \
  --stack-name <stack-name> \
  --template-body file://customer-bootstrap.template.json \
  --parameters file://parameters.json \
  --capabilities CAPABILITY_NAMED_IAM \
  --region <region>
```

**2. Apply the guardrails**

Before your AWS Organizations owner reviews the three [required SCPs](https://docs.braintrust.dev/admin/deployment/byoc/aws-security.md#bootstrap-security-controls), confirm that they contain your final deployment values, including the license secret ARN. The package includes an optional script that prepares the policy JSON, or you can use your own process.

After review, attach the SCPs to the BYOC account, or confirm that equivalent controls already apply. Braintrust never attaches SCPs.

**3. Return the outputs**

When the stack reaches `CREATE_COMPLETE`, export its ID and outputs:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
aws cloudformation describe-stacks \
  --stack-name <stack-name> \
  --region <region> \
  --query 'Stacks[0].{StackId:StackId,Outputs:Outputs}' \
  --output json > byoc-bootstrap-outputs.json
```

Send Braintrust `byoc-bootstrap-outputs.json`. It contains the stack ID, account ID, Region, deployment role ARN, Terraform state bucket, operation log bucket, and license secret ARN, but no External ID or secret values. Then securely delete `parameters.json`.

## 4. Deploy and validate

Braintrust checks its access, your account configuration, required services, and quotas without deploying the data plane. These checks cover the Region, roles, buckets, and license secret metadata. Validation doesn't read the license value or the contents of Terraform state. Braintrust then reviews and confirms the Terraform plan and applies the deployment. Maintenance notice and coordination follow your agreement.

You and Braintrust confirm the endpoint, organization routing, capacity, audit logging, and SIEM export. Braintrust then connects your organization to the new data plane.

## What runs in your account

Braintrust deploys the data plane with the [Braintrust AWS Terraform module](https://github.com/braintrustdata/terraform-aws-braintrust-data-plane). A deployment includes:

* **Endpoint:** CloudFront, which routes API traffic through a VPC origin to an Application Load Balancer (ALB) for the ECS API services. It supports an optional custom domain, ACM certificate, and WAF.
* **Compute:** ECS services for the API, and EC2 Auto Scaling groups for Brainstore.
* **Storage:** RDS PostgreSQL, ElastiCache for Redis, and S3 buckets for Brainstore data, responses, and code bundles.
* **Security and operations:** KMS keys, Secrets Manager secrets, IAM roles, and CloudWatch logs and alarms.
* **Networking:** A main VPC, or a VPC you provide, plus a quarantine VPC, enabled by default, that isolates user-defined code execution.

Custom code scorers execute in quarantine Lambda functions. The quarantine VPC provides network isolation for that execution. The module setting `enable_quarantine_vpc` defaults to `true`. If you disable it, user-defined functions, including custom code scorers, are unavailable. They do not run in the API process instead.

Braintrust provides the standard supported networking setup. Raise any additional DNS, WAF, or connectivity requirements, such as private access, with Braintrust during scoping.

## Next steps

* [BYOC operations and lifecycle](https://docs.braintrust.dev/admin/deployment/byoc/manage.md): Understand how Braintrust operates the deployment after setup.
* [AWS access and security](https://docs.braintrust.dev/admin/deployment/byoc/aws-security.md): Review access, audit records, and revocation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.