Loop runtime

The Loop runtime is an opt-in ECS Fargate service that runs Loop threads in your own data plane, executing each thread in an isolated AWS Lambda MicroVM sandbox. It is disabled by default.

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 sandbox is also what the rest of Loop is built on. The Debugger uses it to diagnose a single trace, and Loop automations use it to do recurring work on a schedule. 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. When enable_loop_runtime is false, your data plane reports no runtime, and users get the older in-browser Loop instead. The Loop page redirects to the organization home, its sidebar entry is hidden, the trace debugger is unavailable, and Loop-backed automations and Slack requests return an error.

Prerequisite - Before you deploy the Loop runtime in your data plane, contact Braintrust to confirm Loop is enabled for your organization. Until it is, Loop stays unavailable in the Braintrust UI even after the runtime is running.

Enable the runtime

The runtime doesn’t depend on enable_ecs_api, which controls only whether CloudFront routes API traffic to ECS. It works either way, because its URL reaches both the ECS API tasks and the Lambda API handlers.

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

  enable_loop_runtime              = true
  loop_runtime_sandbox_egress_mode = "internet" # Opt in to outbound internet access

  # ... other configuration ...
}

On module v6.7.0 and later, loop_runtime_sandbox_egress_mode defaults to "restricted", which blocks all outbound network access from sandbox MicroVMs. Modules v6.6.0 and earlier default to "internet". 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 runtime image floats. modules/loop-runtime-ecs/VERSIONS.json pins it to latest-2.x rather than an exact version, so a new image can roll out without a module upgrade. Set loop_runtime_version_override to pin an exact tag.

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 cover the runtime’s operation. They don’t include LLM calls, tool calls, or the contents of your traces. If your deployment can’t send this telemetry, leave enable_loop_runtime set to false 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 deploys the version it ships with.
`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_org_name`	`"*"`	Organization this Loop runtime serves. `"*"` allows any organization.
`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.

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

Telemetry

Configuration reference

Next steps

​What the runtime provides

​Enable the runtime

​Telemetry

​Configuration reference

​Next steps

What the runtime provides

Enable the runtime

Telemetry

Configuration reference

Next steps