Loop runtime

The Loop runtime is an opt-in ECS Fargate service that runs Loop threads in your own data plane, using isolated AWS Lambda MicroVM sandboxes for command execution and investigation tasks. It is disabled by default, so Loop, the Debugger, and Patterns are unavailable until you enable it.

This page applies to AWS deployments using Terraform module v6.5.2 or later. The Loop runtime is not available on GCP or Azure.

What the runtime provides

Loop does its investigation work in a sandbox, an isolated environment where it reads, searches, and lists trace files directly and runs commands against your data. That is what lets it work through a trace too large to read in one pass, and keep going on a long investigation instead of being bound to a browser session. Threads persist, so users can leave and resume them. The Loop runtime and its isolated sandboxes also support the Debugger, which investigates individual traces, and Loop automations, which perform recurring work on a schedule. Patterns runs as a scheduled Loop automation, so it requires the runtime too. See What Loop can do for the full range. On Braintrust-hosted deployments, Braintrust provides the sandbox. Self-hosted deployments provide it themselves by enabling this service.

Enable the runtime

Set two variables in your data plane module and apply. One deploys the ECS service and its sandbox, and the other decides whether those sandboxes can reach the network.

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

  enable_loop_runtime              = true
  loop_runtime_sandbox_egress_mode = "restricted" # Recommended. No outbound network access from sandboxes.

  # ... other configuration ...
}

enable_loop_runtime deploys the ECS service and its MicroVM sandbox. It is false by default. It doesn’t depend on enable_ecs_api, which controls only whether CloudFront routes API traffic to ECS. The runtime works either way, because its URL reaches both the ECS API tasks and the Lambda API handlers. loop_runtime_sandbox_egress_mode controls whether sandbox MicroVMs can reach the network. Braintrust recommends "restricted", which is the module default and how Braintrust runs its own deployment.

"restricted": The module creates a dedicated VPC for sandboxes, with a security group that has no egress rules and a Route 53 Resolver DNS firewall that blocks every domain. Sandboxes have no outbound network access and can’t resolve names. Two constraints come with it: the VPC uses the 10.255.0.0/16 CIDR block, which you can’t configure, and you can’t supply an existing VPC for it, including your quarantine VPC, which has no DNS firewall.
"internet": Sandboxes use an AWS-managed internet egress connector and can reach the public internet.

Any value other than exactly "internet" is treated as restricted. On module v6.7.0 and later, the default is "restricted". Modules v6.6.0 and earlier default to "internet", so set the variable explicitly before upgrading if your sandboxes need outbound internet access. On module v6.5.2 and later, the runtime sends Loop’s LLM calls through your deployment’s own AI proxy. Earlier versions routed them to gateway.braintrust.dev once enable_ecs_api was set. Upgrade to v6.5.2 or later before enabling the runtime if your deployment must keep inference traffic inside your network. See Braintrust Gateway.

The Loop runtime image isn’t pinned to the module version. The module tracks the latest 2.x release, so a new runtime image can roll out to your deployment without a Terraform change. Set loop_runtime_version_override to pin an exact tag.

Enable Patterns

Applying the runtime makes Loop and the Debugger available across your organization, but it doesn’t start Patterns. Each project turns Patterns on separately, and the person who does it needs permission to create project automations. See Enable Patterns.

Telemetry

On module v6.7.0 and later, the Loop runtime sends metrics and traces for its own service to Braintrust’s control plane, in addition to whatever telemetry types your deployment configures. Braintrust uses them to diagnose runtime problems while the service stabilizes, and you can’t turn them off while the runtime is enabled. These traces describe the runtime’s operation and can include model and tool identifiers, timing information, and errors. If your deployment can’t send this telemetry, leave the Loop runtime disabled and contact Braintrust.

Configuration reference

Variable	Default	Description
`enable_loop_runtime`	`false`	Deploy the Loop runtime ECS service and its MicroVM sandbox.
`loop_runtime_version_override`	`null`	Pin the Loop runtime image and MicroVM guest artifact to a specific version tag. When unset, the module tracks the latest 2.x release.
`loop_runtime_task_cpu`	`2048`	CPU units for each Loop runtime task. 1024 CPU units equal 1 vCPU.
`loop_runtime_task_memory`	`8192`	Memory (MiB) for each Loop runtime task.
`loop_runtime_ephemeral_storage_gib`	`null`	Task ephemeral storage in GiB (21 to 200). `null` uses the Fargate default of 20.
`loop_runtime_min_capacity`	`1`	Minimum number of running Loop runtime tasks.
`loop_runtime_max_capacity`	`4`	Maximum number of running Loop runtime tasks.
`loop_runtime_target_cpu_utilization`	`40`	Target average CPU utilization percentage for autoscaling.
`loop_runtime_target_memory_utilization`	`50`	Target average memory utilization percentage for autoscaling.
`loop_runtime_log_retention_days`	`14`	CloudWatch log retention in days. Must be a valid CloudWatch Logs retention value.
`loop_runtime_enable_execute_command`	`false`	Enable ECS Exec on the Loop runtime service.
`loop_runtime_alb_deregistration_delay`	`900`	Deregistration delay in seconds for the Loop runtime ALB target group.
`loop_runtime_extra_env_vars`	`{}`	Extra environment variables merged into the Loop runtime container.
`loop_runtime_sandbox_egress_mode`	`"restricted"`	Outbound network mode for sandbox MicroVMs. `"restricted"` blocks all outbound network access. Exactly `"internet"` uses AWS-managed internet egress. Any value other than `"internet"` is treated as restricted.
`loop_runtime_microvm_minimum_memory_mib`	`2048`	Minimum memory (MiB) provisioned for each sandbox MicroVM.
`loop_runtime_microvm_max_idle_duration_seconds`	`900`	Seconds without traffic before a sandbox MicroVM auto-suspends.
`loop_runtime_microvm_suspended_duration_seconds`	`28800`	Seconds a suspended MicroVM remains resumable before termination.
`loop_runtime_microvm_maximum_duration_seconds`	`28800`	Maximum MicroVM lifetime across running and suspended states.
`loop_runtime_microvm_auth_token_expiration_minutes`	`30`	Endpoint auth token lifetime in minutes for MicroVM invocations.
`enable_loop_runtime_microvm_runtime_logs`	`false`	Export MicroVM stdout and stderr to CloudWatch. Output can include sandbox contents.

On module v6.8.1 and later, the runtime serves the organization named by braintrust_org_name. Earlier versions used a separate loop_runtime_org_name variable. Remove it from your configuration before you upgrade, or the plan fails with An argument named "loop_runtime_org_name" is not expected here.

Next steps

Learn what Loop can do once the runtime is running.
Review thread and sandbox limits that apply to your users.
Configure networking and connectivity for the rest of your deployment.

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

What the runtime provides

Enable the runtime

Enable Patterns

Telemetry

Configuration reference

Next steps

​What the runtime provides

​Enable the runtime

​Enable Patterns

​Telemetry

​Configuration reference

​Next steps

What the runtime provides

Enable the runtime

Enable Patterns

Telemetry

Configuration reference

Next steps