# Install OX Runtime Sensor on AWS ECS Terraform

Deploy the OX Runtime Sensor as an ECS Daemon service, one task per EC2 container instance, using the provided Terraform module. The API key is managed using AWS Secrets Manager.

## Prerequisites

* ECS cluster backed by EC2 instances (not Fargate) with Linux kernel v5.10 and later
* Terraform v1.3 and later
* AWS credentials with permissions for ECS, IAM, CloudWatch Logs, and Secrets Manager
* [An OX API key](/secure-runtime/ox-runtime-sensor.md).

## Step 1: Configure the AWS provider

Add the AWS provider to your Terraform configuration:

```hcl
provider "aws" {
  region  = "<AWS_REGION>"   # e.g. "us-east-1"
  profile = "<AWS_PROFILE>"  # omit if using environment credentials or an IAM role
}
```

## Step 2: Configure the Terraform module

Add the module to your Terraform configuration. The tarball URL is provided by OX Security and has the sensor image, registry, and API endpoint already baked in.

1. Provide the API key directly. The module creates the Secrets Manager secret.

```hcl
module "ox_runtime_sensor" {
  source = "https://charts.cloud.ox.security/terraform/aws-ecs-sensor-latest.tar.gz"

  # Required
  ecs_cluster_name = "<ECS_CLUSTER_NAME>"
  ox_api_key       = "<API_KEY>"

  # Optional — shown in OX UI and attached to every event
  # ox_cluster_name     = "<CLUSTER_NAME>"    # defaults to ecs_cluster_name if omitted
  # ox_cloud_provider   = "aws"                # default, no need to change for ECS
  # ox_cloud_region     = "<AWS_REGION>"       # auto-detected from AWS provider
  # ox_cloud_account_id = "<AWS_ACCOUNT_ID>"   # auto-detected from AWS caller identity
}
```

2. (Alternative) Bring your own secret. If you manage secrets externally (for example, using External Secrets Operator or a shared secret store), pass the ARN instead.

```hcl
module "ox_runtime_sensor" {
  source = "https://charts.cloud.ox.security/terraform/aws-ecs-sensor-latest.tar.gz"

  ecs_cluster_name      = "<ECS_CLUSTER_NAME>"
  create_secret         = false
  ox_api_key_secret_arn = "<SECRET_ARN>"

  # Optional — shown in OX UI and attached to every event
  # ox_cluster_name     = "<CLUSTER_NAME>"    # defaults to ecs_cluster_name if omitted
  # ox_cloud_provider   = "aws"                # default, no need to change for ECS
  # ox_cloud_region     = "<AWS_REGION>"       # auto-detected from AWS provider
  # ox_cloud_account_id = "<AWS_ACCOUNT_ID>"   # auto-detected from AWS caller identity
}
```

> **Pinning a specific version:** Replace `latest` with the versioned filename (for example, `aws-ecs-sensor-v0.20250401.1.tar.gz`). OX Security publishes the full version history at `https://charts.cloud.ox.security/terraform/`.

## Step 3: Apply

```
terraform init
terraform plan
terraform apply
```

Terraform creates:

* An ECS task definition with the required Linux capabilities and volume mounts
* A Daemon service (one task per EC2 instance in the cluster)
* An IAM task execution role with `secretsmanager:GetSecretValue` permission
* A CloudWatch log group for sensor logs (configurable)

## [Step 4: Connect to OX Runtime Sensor](/secure-runtime/ox-runtime-sensor.md)

## Configuration reference

| Variable                        | Required                               | Default                                | Description                                                                          |
| ------------------------------- | -------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------ |
| `ecs_cluster_name`              | **yes**                                | —                                      | Name of the ECS cluster to deploy into (max 35 characters)                           |
| `ox_api_key`                    | **yes** (when `create_secret = true`)  | —                                      | OX API key. The module creates a Secrets Manager secret from this value              |
| `ox_api_key_secret_arn`         | **yes** (when `create_secret = false`) | —                                      | ARN of an existing Secrets Manager secret containing the OX API key                  |
| `create_secret`                 | no                                     | `true`                                 | Set to `false` to use an existing Secrets Manager secret via `ox_api_key_secret_arn` |
| `ox_cluster_name`               | no                                     | same as `ecs_cluster_name`             | Label shown in the OX UI. Set this if you want a friendlier or different name        |
| `ox_cloud_provider`             | no                                     | `aws`                                  | Cloud provider label injected into every event                                       |
| `ox_cloud_region`               | no                                     | auto-detected from AWS provider        | AWS region injected into every event                                                 |
| `ox_cloud_account_id`           | no                                     | auto-detected from AWS caller identity | AWS account ID injected into every event                                             |
| `cloudwatch_logs_enabled`       | no                                     | `true`                                 | Create a CloudWatch log group and forward sensor logs                                |
| `cloudwatch_log_retention_days` | no                                     | `7`                                    | Log retention in days (`0` = never expire)                                           |
| `host_network`                  | no                                     | `true`                                 | Use host network mode (required for IMDSv2 access)                                   |

### Uninstall

```
terraform destroy
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ox.security/secure-runtime/ox-runtime-sensor/install-ox-runtime-sensor-on-aws-ecs-terraform.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.