Home / Documentation / BYOC Setup
Documentation

Getting Started

CLI

Infrastructure

Community

BYOC Setup

Deploy TraceLoom infrastructure in your own AWS account using a guided 3-step wizard. All test execution happens on your EC2 instances, and all Playwright traces stay in your S3 bucket — zero data egress. Setup takes approximately 5 minutes.

AWS costs apply: BYOC deploys EC2 Spot instances, S3 buckets, SQS queues, and DynamoDB tables into your AWS account. These resources incur standard AWS charges (typically $3–5/month for light usage). Resources are billed by AWS, not TraceLoom. See Cost Estimate below for details.

Overview

BYOC (Bring Your Own Cloud) deploys TraceLoom's data plane into your AWS account via CloudFormation. Your test traces never leave your infrastructure. The architecture:

  • TraceLoom control plane — manages test scheduling, sharding, and result aggregation. Hosted by TraceLoom.
  • Your AWS account — runs EC2 Spot instances, stores traces in S3, queues jobs in SQS. You own and control all of this.
  • Cross-account IAM role — TraceLoom assumes this role with a unique ExternalId tied to your account. Revoke at any time by deleting the CloudFormation stack.

Your Playwright traces, test artifacts, and test data never leave your infrastructure. TraceLoom reads test results and metadata — it does not retain your actual trace files.

Prerequisites

  • An AWS account with permission to create IAM roles, S3 buckets, SQS queues, DynamoDB tables, and EC2 Launch Templates
  • Your AWS Account ID (12-digit number from the AWS console)
  • Preferred AWS region (e.g. us-east-1)
  • TraceLoom account — sign up free

Step 1: Configure

In the TraceLoom app, navigate to Settings → BYOC Setup. Enter your AWS Account ID and preferred region. TraceLoom generates a unique ExternalId tied to your account — this is embedded automatically in the CloudFormation template and used to prevent confused deputy attacks.

Step 2: Deploy

Click Launch CloudFormation Stack. This opens the AWS CloudFormation Quick Create page pre-populated with all required parameters. The template URL is: 

https://traceloom-public-templates.s3.amazonaws.com/latest/data-plane.yaml

Review the parameters (Account ID, Region, and ExternalId are pre-filled), acknowledge IAM capabilities, and click Create Stack. TraceLoom polls every 10 seconds and shows live stack status in the wizard.

Step 3: Validate

Once the stack reaches CREATE_COMPLETE, TraceLoom automatically runs a validation check. It verifies connectivity to each resource and reports the result inline. If validation fails, the page shows remediation hints per resource — for example:

  • S3 bucket not accessible — check bucket policy
  • IAM role ExternalId mismatch — verify stack parameters match your wizard settings
  • SQS queue unreachable — confirm the queue was created in the correct region

Resources Created

The CloudFormation template creates the following resources in your AWS account. All are fully visible in your AWS Console:

Resource Purpose
IAM Role (TraceLoom Data Plane Role) Cross-account access with ExternalId condition
S3 Bucket Test trace storage (.trace.zip files)
SQS Queue + Dead Letter Queue Test job dispatch and failure isolation
DynamoDB Tables (4) Run state, test results, schedules, configuration
EC2 Launch Template (t3.medium) Spot instance fleet for test execution

Cost Estimate

Approximate monthly cost for a team running approximately 1,000 tests/month:

  • EC2 Spot (t3.medium, ~20 hrs/month): ~$0.80
  • S3 storage (trace files, ~10 GB): ~$0.23
  • SQS: ~$0.40
  • DynamoDB (on-demand): ~$1.50
  • Total: ~$3–5/month

Costs scale with test volume. Zero cost when idle — EC2 Spot instances terminate automatically when no jobs are queued.

Troubleshooting

  • Stack stuck in CREATE_IN_PROGRESS — check the CloudFormation Events tab for the first FAILED event. Common causes: IAM permission boundaries in your account, VPC limits, or S3 bucket name conflicts.
  • Validation fails for IAM role — ensure the ExternalId in the stack matches the one shown in the TraceLoom wizard. The values must match exactly.
  • S3 access denied — the IAM role must have s3:PutObject on the bucket created by this stack.
  • EC2 quota exceeded — your account may need a Spot instance quota increase. Request one in the EC2 console under Service Quotas.

Security Model

TraceLoom uses cross-account IAM role assumption with ExternalId (confused deputy protection). TraceLoom's control plane ARN is scoped to assume only your specific role. Your AWS credentials are never stored by TraceLoom — all access uses temporary STS credentials.

Data Location
Playwright trace files (.trace.zip) Customer S3 bucket
Test run metadata TraceLoom DynamoDB
API keys, schedules TraceLoom DynamoDB
CloudWatch logs Customer CloudWatch

Note on secrets: Environment variable secrets (Settings → Secrets) are stored in TraceLoom's infrastructure, not your AWS account. Values are encrypted using AWS KMS before storage and are never returned in plaintext via the API. If you require secrets to remain entirely within your AWS account, store them in AWS Secrets Manager and reference them from your test code directly.

Back to Getting Started

Last updated: March 2026

>