> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Loop runtime
> Run Loop threads inside a self-hosted AWS data plane with an opt-in ECS service that executes each thread in an isolated MicroVM sandbox.
The Loop runtime is an opt-in ECS Fargate service that runs [Loop](/docs/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](/docs/observe/debug-traces) uses it to diagnose a single trace, and [Loop automations](/docs/loop/automations) use it to do recurring work on a schedule. See [What Loop can do](/docs/loop/capabilities) 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**](https://www.braintrust.dev/app/~/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](mailto:support@braintrust.dev) 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.
```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](/docs/admin/self-hosting/configure/networking#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](/docs/admin/self-hosting/configure/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](mailto:support@braintrust.dev).
## 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](/docs/loop/capabilities) once the runtime is running.
* Review [thread and sandbox limits](/docs/loop/manage#sandboxes) that apply to your users.
* Configure [networking and connectivity](/docs/admin/self-hosting/configure/networking) for the rest of your deployment.