> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usetero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Config

> Complete configuration reference for Edge

Config lists every Edge configuration option.

## Configuration File

Edge uses a JSON configuration file. Pass the path as the first argument:

```bash theme={null}
./edge config.json
```

### Full Example

```json config.json theme={null}
{
  "listen_address": "0.0.0.0",
  "listen_port": 8080,
  "upstream_url": "https://agent-http-intake.logs.datadoghq.com",
  "logs_url": "https://agent-http-intake.logs.datadoghq.com",
  "metrics_url": "https://api.datadoghq.com",
  "log_level": "info",
  "max_body_size": 1048576,
  "service": {
    "name": "edge",
    "namespace": "production",
    "resource_attributes": [
      { "key": "deployment.environment", "value": "production" }
    ],
    "labels": [{ "key": "team", "value": "platform" }]
  },
  "policy_providers": [
    {
      "id": "local",
      "type": "file",
      "path": "/etc/edge/policies.json"
    },
    {
      "id": "remote",
      "type": "http",
      "url": "${TERO_CONTROL_PLANE_URL}/v1/policy/sync",
      "poll_interval": 30,
      "headers": [
        {
          "name": "Authorization",
          "value": "Bearer ${TERO_API_TOKEN}"
        }
      ]
    }
  ]
}
```

<Note>
  Any string value can reference an environment variable with `${VAR}` (for
  example `${TERO_API_TOKEN}`). See [Environment
  Variables](#environment-variables).
</Note>

## Configuration Reference

<Info>
  Edge supports up to 8,000 policies. Open an [issue on
  GitHub](https://github.com/usetero/edge/issues/new) if you need more.
</Info>

### Server Settings

| Field            | Type   | Default       | Description                                      |
| ---------------- | ------ | ------------- | ------------------------------------------------ |
| `listen_address` | string | `"127.0.0.1"` | IP address to bind to                            |
| `listen_port`    | number | `8080`        | Port to listen on                                |
| `max_body_size`  | number | `1048576`     | Maximum request body size in bytes (1MB default) |
| `log_level`      | string | `"info"`      | Logging level: `debug`, `info`, `warn`, `err`    |

### Upstream Settings

| Field          | Type   | Required | Description                                                               |
| -------------- | ------ | -------- | ------------------------------------------------------------------------- |
| `upstream_url` | string | Yes      | Default upstream destination (fallback when specific URLs not set)        |
| `logs_url`     | string | No       | Upstream destination for log endpoints (falls back to `upstream_url`)     |
| `metrics_url`  | string | No       | Upstream destination for metrics endpoints (falls back to `upstream_url`) |

### Service Settings

The `service` object identifies this Edge instance to the control plane and
attaches metadata to policy sync requests. Always set `name`, `namespace`, and
`version` — the control plane uses them to scope and match policies to this
service. `resource_attributes` and `labels` are optional but recommended.

```json theme={null}
{
  "service": {
    "name": "edge",
    "namespace": "production",
    "resource_attributes": [
      { "key": "deployment.environment", "value": "production" }
    ],
    "labels": [{ "key": "team", "value": "platform" }]
  }
}
```

| Field                 | Type   | Required    | Description                                                   |
| --------------------- | ------ | ----------- | ------------------------------------------------------------- |
| `name`                | string | Recommended | Service name (default `"tero-edge"`)                          |
| `namespace`           | string | Recommended | Service namespace (default `"tero"`)                          |
| `version`             | string | Recommended | Service version (default `"latest"`)                          |
| `resource_attributes` | array  | No          | OTel resource attributes (`{key, value}`) sent on policy sync |
| `labels`              | array  | No          | Free-form labels (`{key, value}`) sent on policy sync         |

<Note>`instance_id` is generated at startup and is not configurable.</Note>

### Policy Providers

The `policy_providers` array configures where Edge loads policies from.

#### File Provider

Loads policies from a local file and watches for changes.

```json theme={null}
{
  "id": "local",
  "type": "file",
  "path": "/etc/edge/policies.json"
}
```

| Field  | Type   | Required | Description                         |
| ------ | ------ | -------- | ----------------------------------- |
| `id`   | string | Yes      | Unique identifier for this provider |
| `type` | string | Yes      | Must be `"file"`                    |
| `path` | string | Yes      | Path to the policy file             |

Edge watches the file with inotify (Linux) or kqueue (macOS) and applies changes
on save.

#### HTTP Provider

Loads policies from an HTTP endpoint with periodic polling.

```json theme={null}
{
  "id": "remote",
  "type": "http",
  "url": "https://api.example.com/policies",
  "poll_interval": 30,
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer token"
    }
  ]
}
```

| Field           | Type   | Required | Description                         |
| --------------- | ------ | -------- | ----------------------------------- |
| `id`            | string | Yes      | Unique identifier for this provider |
| `type`          | string | Yes      | Must be `"http"`                    |
| `url`           | string | Yes      | URL to fetch policies from          |
| `poll_interval` | number | No       | Seconds between policy fetches      |
| `headers`       | array  | No       | HTTP headers to include in requests |

### Prometheus Settings

The optional `prometheus` object bounds memory use when filtering Prometheus
scrapes (relevant to distributions that handle metrics).

```json theme={null}
{
  "prometheus": {
    "max_input_bytes_per_scrape": 10485760,
    "max_output_bytes_per_scrape": 10485760
  }
}
```

| Field                         | Type   | Default    | Description                                         |
| ----------------------------- | ------ | ---------- | --------------------------------------------------- |
| `max_input_bytes_per_scrape`  | number | `10485760` | Max bytes read from upstream per scrape (10MB)      |
| `max_output_bytes_per_scrape` | number | `10485760` | Max bytes forwarded to the client per scrape (10MB) |

## Policy File Format

Define policies in a JSON file:

```json policies.json theme={null}
{
  "policies": [
    {
      "id": "policy-1",
      "name": "Human-readable name",
      "description": "What this policy does",
      "enabled": true,
      "log": {
        "match": [...],
        "keep": "...",
        "transform": {...}
      }
    },
    {
      "id": "policy-2",
      "name": "Another policy",
      "metric": {
        "match": [...],
        "keep": true
      }
    }
  ]
}
```

See the [Policies](/edge/policy-reference/log-filter) section for detailed
policy configuration.

## Environment Variables

Edge reads environment variables two ways.

### Value Substitution

Any string value in the config file can reference an environment variable with
`${VAR}`. The variable is resolved when the config loads:

```json theme={null}
{
  "upstream_url": "https://agent-http-intake.logs.${TERO_DD_REGION}.datadoghq.com",
  "policy_providers": [
    {
      "id": "remote",
      "type": "http",
      "url": "${TERO_CONTROL_PLANE_URL}/v1/policy/sync",
      "headers": [
        { "name": "Authorization", "value": "Bearer ${TERO_API_TOKEN}" }
      ]
    }
  ]
}
```

* Unset variables resolve to an empty string.
* Use `$${VAR}` to emit a literal `${VAR}` without substitution.

### Field Overrides

A `TERO_`-prefixed environment variable overrides the matching config field. The
name is the field path in `SCREAMING_SNAKE_CASE`, with nested fields joined by
`_`. Overrides win over the file.

| Variable             | Overrides       |
| -------------------- | --------------- |
| `TERO_LOG_LEVEL`     | `log_level`     |
| `TERO_LISTEN_PORT`   | `listen_port`   |
| `TERO_UPSTREAM_URL`  | `upstream_url`  |
| `TERO_MAX_BODY_SIZE` | `max_body_size` |
| `TERO_SERVICE_NAME`  | `service.name`  |

```bash theme={null}
TERO_LOG_LEVEL=debug TERO_LISTEN_PORT=9090 ./edge config.json
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Operations" icon="server" href="/edge/edge-reference/operations">
    Logging, health checks, and resource requirements
  </Card>

  <Card title="Log Filtering" icon="filter" href="/edge/policy-reference/log-filter">
    Configure log filtering policies
  </Card>
</CardGroup>