> ## 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 [**<Icon icon="blend" /> Loop**](/docs/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.

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

## 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](/docs/observe/debug-traces), which investigates individual traces, and [Loop automations](/docs/loop/automations), which perform recurring work on a schedule. [**<Icon icon="scan-search" /> Patterns**](/docs/observe/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.

```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 = "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](/docs/admin/self-hosting/configure/networking#braintrust-gateway).

<Note>
  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.
</Note>

## 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](/docs/observe/patterns/enable).

## 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 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](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 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](/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.