Install Brainbase on AWS

Deploy Brainbase into your AWS account through AWS Marketplace, then verify login, model inference, and sandbox execution. This guide covers the public CloudFormation release 2026-09-16.1, checked September 17, 2026. You do not need Brainbase's source repositories, CDK, Docker, or a local development environment.

1. Prepare your AWS account

• Region: use US East (N. Virginia), us-east-1. This template does not support other regions or AWS partitions.
• Account: subscribe and deploy in the intended customer account. Check its account ID in the console; do not assume the organization management account transfers model access, quotas, or SES approval to member accounts.
• Permissions: use an approved deployment role that can create CloudFormation, IAM roles/policies and pass roles, VPC/networking, EC2/EBS, ECS/Fargate, ECR, Lambda/MicroVM, CodeBuild, S3, Secrets Manager, Route 53, ACM, WAF, SES, SNS, and CloudWatch resources. Organization SCPs and permission boundaries must permit the deployment. Do not use root or send AWS credentials to Brainbase.
• Existing resources: use an account without another Brainbase appliance. This release uses fixed resource names; changing only the stack name does not isolate a second installation.
• Contacts: choose the first user inbox and a monitored operations inbox. They can differ. Have an account owner available for model terms and SES production-access acknowledgment.
• Capacity: complete Model Access & Quotas. Check infrastructure quotas before deploying and resolve model/sandbox capacity before running agents.
• Budget and data flows: review your Marketplace offer and Operations & Troubleshooting before purchase. AWS infrastructure and Bedrock usage are billed separately from Brainbase platform charges.

2. Choose and delegate your domain

Use a deployment subdomain such as brainbase.example.com that you control. Your app will be https://app.brainbase.example.com. The installer also creates API, authentication, LLM, webhook, and integration hostnames beneath it. Enter the domain without https://, app., a path, or a trailing dot.

1. In Route 53, identify a public hosted zone in the deployment account that serves your deployment domain. Record its hosted zone ID. A private zone is not sufficient.
2. If your parent domain uses another DNS provider or AWS account, create a public hosted zone for brainbase.example.com in the deployment account. At the parent DNS provider, delegate that subdomain using all four Route 53 name servers. Do not replace the parent domain nameservers or email records.
3. Verify the public delegation reaches that exact hosted zone before creating the stack. The installer writes certificate validation, host aliases, and SES DKIM records there; it cannot configure an external DNS provider for you.

Follow AWS's subdomain delegation procedure. You do not need to move your main website or corporate email to AWS.

DOMAIN=brainbase.example.com
HOSTED_ZONE_ID=Z_REPLACE_WITH_YOUR_CHILD_ZONE_ID

aws sts get-caller-identity --query Account --output text
aws route53 get-hosted-zone --id "$HOSTED_ZONE_ID" \
  --query '{Domain:HostedZone.Name,Private:HostedZone.Config.PrivateZone,NameServers:DelegationSet.NameServers}'
dig +short NS "$DOMAIN"

3. Subscribe and select the release

1. In AWS Marketplace, find Brainbase - Agent Platform. Verify the product code is 6mq6xj2rkcoaj64hhp4v6vosy against the product information or your offer before accepting.
2. Review pricing and terms. If Brainbase sent a private offer, verify its intended account and offer ID and accept that offer. A public offer and a private offer for the same product are alternative commercial terms, not two stacks to install.
3. Wait until the subscription/agreement is active in the deployment account. Downloading the template alone does not authorize access to Marketplace container images.
4. Continue to configuration/launch and select the CloudFormation delivery option in us-east-1. Use release 2026-09-16.1 for the setup documented here; for newer releases, also read their release notes.

4. Create the CloudFormation stack

Open CloudFormation in us-east-1. Choose Create stack, with new resources, and use the template URL supplied by the selected Marketplace version. The 2026-09-16.1 template is public. Choose a stack name, such as brainbase, and fill in these parameters.

1. Review the template, options, and IAM capability acknowledgments with your administrator, then create the stack.
2. Watch Events until CREATE_COMPLETE. Allow roughly 15 minutes, with additional time for DNS, image builds, or AWS capacity. Investigate the first failed resource instead of repeatedly starting new stacks.
3. The template generates credentials, initializes the database/schema, pulls release images, and builds the sandbox image in your account. Do not run separate database initialization scripts.
4. In ECS, open the bb-appliance cluster. Check services have running tasks matching their desired count and no repeated task failures. Open https://api.<your-domain>/healthz and expect HTTP 200; open the app hostname and verify HTTPS has a valid certificate.

The deployment creates a VPC, NAT gateway, ALB and TLS certificates, 15 Fargate services, PostgreSQL on EC2 with encrypted storage, installation helpers, sandbox image resources, buckets, secrets, logging, and alarms. You operate these resources in your account. See troubleshooting if installation or health checks fail.

5. Enable email and sign in

1. Complete Login Email Setup: verify the sender/DKIM, confirm both SNS subscriptions, establish feedback handling, and obtain SES production access in this account and region. A sandbox-only pilot has extra recipient restrictions.
2. Open https://app.<your-domain> in your browser, choose Magic Link, and enter the exact FirstUserEmail used during deployment. Provisioning that account does not itself send a login email.
3. Open the newest login email in the same browser/profile that requested it. Complete the application onboarding prompts and verify you reach your workspace. Keep the link private; it is a sign-in credential.
4. Use your deployment URL, not the hosted SaaS app. A SaaS account, Google login, or SSO button is not proof that the equivalent provider is configured on this installation.

Public self-signup stays disabled. If you left FirstUserEmail empty, have the deployment administrator update the stack with that parameter or contact help@brainbaselabs.com for administrator-assisted provisioning. Changing the parameter does not remove an earlier user or transfer their team permissions.

6. Run a real agent task

1. In your deployment, follow Building Your First Agent using the UI. Choose a model available in this release and approved for this AWS account. Do not use the SaaS API URLs shown in general examples.
2. Keep the first agent minimal: do not enable optional browser, memory, or external integrations just to test the core stack.
3. Ask the agent: "Use your shell tool to print the current working directory, create a file named brainbase-smoke.txt containing hello from Brainbase, read it back, and report the result. Do not install packages or access external services." This consumes model tokens and sandbox resources.
4. In Tasks, verify a successful model response, a machine assignment, actual successful shell/file tool calls, and the expected file content. A machine ID or text-only response alone does not prove sandbox execution.
5. Send a follow-up that reads the same file. Test a fresh task too, with enough quota for another VM if the application allocates one. Record task IDs and timings; do not promise a fixed startup duration.
6. Test each optional integration separately before enabling it for users. A working core task does not validate third-party credentials or permissions.

Continue with Operations & Troubleshooting for monitoring, backups, upgrades, costs, and safe cleanup.