> ## Documentation Index
>
> Fetch the complete documentation index at: [/llms.txt](https://cosmo-docs.wundergraph.com/llms.txt)
>
> Use this file to discover all available pages before exploring further.

[Skip to main content](https://cosmo-docs.wundergraph.com/router/configuration#content-area)

The router provides three different ways of customization:

1. **Configure the router runtime:** You can specify a for convenience or pass [environment variables](https://cosmo-docs.wundergraph.com/router/configuration#environment-variables). In both ways, you can configure the global behavior of the router. For a full reference of all available options see below or use your [IDE of choice](https://cosmo-docs.wundergraph.com/router/configuration#config-validation-and-auto-completion).
2. **Configure how your graph is served:** This file can be provided as config option or is pulled automatically from the cdn. It contains information on how to resolve your federated schema. The engine uses the information to build a highly optimized query planner. For more information see to build the file locally for development or to download the latest production version.
3. **Customize the router programatically through** Go [modules](https://cosmo-docs.wundergraph.com/router/custom-modules). It is unlikely that we will provide every possible feature as an in-built functionality. For advanced use cases or more control, you can build Go modules and compile the Router in a few commands. If you are uncertain about if your use case should be implemented as a custom module, don’t hesitate to open an issue. We might already have a plan for this or can assist you with the implementation.

**Recommendation** Create a config file and use environment variable expansion
to avoid storing secrets on the file system.

**Experimental options**Options starting with the prefix `experiment_` are unstable, and do not fall under any API stability guarantees. They may be updated or removed in future versions without a deprecation notice.

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#config-file)  Config File

For convenience, you can create a `config.yaml` to specify all router options. Start the router in the same directory or pass the path to the file as a `CONFIG_PATH` environment variable.

config.yaml

```
version: "1"

graph:
  token: "${GRAPH_API_TOKEN}"
```

Values specified in the config file have **precedence** over Environment
variables. This also includes empty values so only specify values that should
be overwritten. That means, you can see the config file as a single source of
truth.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#multiple-config-files)  Multiple Config Files

The router allows you to have multiple configuration files, enabling you to override and separate configurations into more manageable chunks. When specifying configuration files, you can simply provide a comma-separated list of file names. You can read more about this [here](https://cosmo-docs.wundergraph.com/router/configuration/config-design).

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#expand-environment-variables)  Expand Environment Variables

You can expand environment variables in the file like this:

config.yaml

```
version: "1"

log_level: "${LOG_LEVEL}"
```

This will replace the value of the environment variable `LOG_LEVEL` with the value of the key `log_level` in your config file. For numeric values, ensure quotes are omitted.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#config-validation-&-auto-completion)  Config Validation & Auto-completion

We know configuration is hard, especially for a software component like the router that can be customized entirely to your needs. In order to simplify this, we use [JSON schema](https://json-schema.org/) to validate the router configuration. This comes with huge benefits, all right at your fingertips:

- Auto-completion
- Documentation (Usage, Examples)
- Detect deprecated fields
- Detect typos or invalid values.

Some options require the router to validate them. This requires starting the router. Once your router has started successfully, you can be sure that your configuration is valid.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#ide-configuration)  IDE Configuration

- **VSCode**: Install the [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) extension in your IDE.
- **JetBrains**: Support out of the box but in some circumstances it conflicts with other default mappings. **Go to**`Languages & Frameworks` -\> `Schemas and DTDs` -\> `JSON Schemas Mappings` configure the mapping yourself.

As the next step, add the following line to the head of your `config.yaml`file. This line informs your IDE, to download the correct JSON schema file to validate the config file.

config.yaml

```
# yaml-language-server: $schema=https://raw.githubusercontent.com/wundergraph/cosmo/main/router/pkg/config/config.schema.json

version: "1"
```

If you want to pin to a specific router version use the following URL:

config.yaml

```
# yaml-language-server: $schema=https://raw.githubusercontent.com/wundergraph/cosmo/router%400.67.0/router/pkg/config/config.schema.json
```

Now, you should get auto-completion .

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#environment-variables)  Environment Variables

Many configuration options can be set as environment variables. For a complete list of options, please look at the [Router](https://cosmo-docs.wundergraph.com/router/configuration#router) config tables.

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#regular-expressions)  Regular Expressions

Many configuration options support regular expressions (Go RE2 syntax). Test patterns at [regex101.com](https://regex101.com/) using the “Golang” flavor.

**Escape dots in metric names:** OpenTelemetry metrics contain dots that must be escaped in regex patterns:

- **Incorrect:**`"wg.operation.hash"` (matches any character)
- **Correct:**`"wg\\.operation\\.hash"` or `'^wg\.operation\.hash$'` (single quotes recommended)

**Common examples:**

```
# Metric exclusion
exclude_metrics:
  - '^wg\.operation\.hash$'       # Exact match
  - '^router\.http\.request\..*'  # Prefix match

# Header matching
headers:
  all:
    request:
      - op: "propagate"
        matching: '(?i)^x-custom-.*'  # Case-insensitive prefix
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#router)  Router

The following sections describe each configuration in detail with all available options and their defaults.

Intervals, timeouts, and delays are specified in Go [duration](https://pkg.go.dev/maze.io/x/duration#ParseDuration) syntax e.g 1s, 5m or 1h.Sizes can be specified in 2MB, 1mib.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| LISTEN\_ADDR | listen\_addr |  | The server listener address. | localhost:3002 |
| CONTROLPLANE\_URL | controlplane\_url |  | The controlplane url. Not required when a static execution config is provided. | [https://cosmo-cp.wundergraph.com](https://cosmo-cp.wundergraph.com/) |
| PLAYGROUND\_ENABLED | playground\_enabled |  | Enables the GraphQL playground on (`$LISTEN_ADDR/`) | true |
| PLAYGROUND\_PATH | playground\_path |  | The path where the playground is served | ”/“ |
| INTROSPECTION\_ENABLED | introspection\_enabled |  | **Deprecated**, use [“introspection.enabled”](https://cosmo-docs.wundergraph.com/router/configuration#introspection) instead. Enables the GraphQL introspection. | true |
| QUERY\_PLANS\_ENABLED | query\_plans\_enabled |  | The Router can return Query plans as part of the response, which might be useful to understand the execution. | true |
| LOG\_LEVEL | log\_level |  | The log level to use. Allowed levels are `"debug"`, `"info"`, `"warn"`, `"error"`, `"panic"`, `"fatal"`. | info |
| JSON\_LOG | json\_log |  | Render the log output in JSON format (true) or human readable (false) | true |
| LOG\_SERVICE\_NAME | log\_service\_name |  | The service name used in the `service` field of log entries. | @wundergraph/router |
| SHUTDOWN\_DELAY | shutdown\_delay |  | Maximum time in seconds the server has to shutdown gracefully. Should be higher than `GRACE_PERIOD` | 60s |
| GRACE\_PERIOD | grace\_period |  | Maximum time in seconds the server has between schema updates to gracefully clean up all resources. Should be smaller than `SHUTDOWN_DELAY` | 30s |
| POLL\_INTERVAL | poll\_interval |  | The interval of how often the router should check for new schema updates | 10s |
| POLL\_JITTER | poll\_jitter |  | The maximum delay added to the poll interval to mitigate thundering herd issues in router fleets scenarios. | 5s |
| HEALTH\_CHECK\_PATH | health\_check\_path |  | Health check path. Returns `200` when the router is alive | /health |
| READINESS\_CHECK\_PATH | readiness\_check\_path |  | Readiness check path. Return `200` when the router is ready to accept traffic, otherwise `503` | /health/ready |
| LIVENESS\_CHECK\_PATH | liveness\_check\_path |  | Liveness check path. Return 200 when the router is alive | /health/live |
| GRAPHQL\_PATH | graphql\_path |  | The path where the GraphQL Handler is served | /graphql |
| PLAYGROUND\_PATH | playground\_path |  | The path where the playground is served | / |
| LOCALHOST\_FALLBACK\_INSIDE\_DOCKER | localhost\_fallback\_inside\_docker |  | Enable fallback for requests that fail to connect to localhost while running in Docker | true |
| DEV\_MODE | dev\_mode |  | Enables pretty log output and allows to use [Advanced Request Tracing (ART)](https://cosmo-docs.wundergraph.com/router/advanced-request-tracing-art) without further security protection. | false |
| INSTANCE\_ID | instance\_id |  | If not specified, a new ID will be generated with each router start. A stable ID ensures that metrics with the same ID are grouped together and the same server can be identified on the platform. |  |
| DEMO\_MODE | demo\_mode |  | Launch the router in demo mode. If no execution config is found, the router will start with a demo execution config and deploy a demo federated graph that can be used for testing purposes. |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-configuration)  Example configuration:

config.yaml

```
version: "1"

log_level: "info"
listen_addr: "localhost:3002"
controlplane_url: "https://cosmo-cp.wundergraph.com"
playground_enabled: true
playground_path: "/"
introspection:
  enabled: true
json_log: true
shutdown_delay: 15s
grace_period: 20s
poll_interval: 10s
health_check_path: "/health"
readiness_check_path: "/health/ready"
liveness_check_path: "/health/live"
router_config_path: ""
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#config-watcher-hot-reloading)  Config watcher hot reloading

The router is capable of reloading itself using an updated config without a full process restart. You can trigger a reload in one of two ways:

- Sending a `SIGHUP` signal to the router process.
- Configuring the `watch_config` section to automatically check the configuration for changes at regular intervals.

config.yaml

```
watch_config:
  enabled: true
  interval: "10s"

startup_delay:
    enabled: false
    maximum: "10s"
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#watch_config-options)  `watch_config` options

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| WATCH\_CONFIG\_ENABLED | watch\_config.enabled |  | Enable automatic configuration reloading at regular intervals. | false |
| WATCH\_CONFIG\_INTERVAL | watch\_config.interval |  | The interval at which the router checks for configuration changes. | 10s |
| WATCH\_CONFIG\_STARTUP\_DELAY\_ENABLED | watch\_config.startup\_delay.enabled |  | Enable a random delay before the first configuration check to avoid thundering herd problems in clusters. | false |
| WATCH\_CONFIG\_STARTUP\_DELAY\_MAXIMUM | watch\_config.startup\_delay.maximum |  | The maximum random delay before the first configuration check. | 10s |

Hot reloading has some limitations:

- Changes to the `watch_config` section are not hot-reloaded.
- Changes to flags and environment variables are not possible.
- `watch_config` based reloads are based on the filesystem’s modification time, edits that somehow circumvent this mechanism will not trigger a reload.

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#access-logs)  Access Logs

For a detailed example, please refer to the [Access Logs](https://cosmo-docs.wundergraph.com/router/access-logs) section.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | access\_logs |  | Enable the access logs. The access logs are used to log the incoming requests. By default, the access logs are enabled and logged to the standard output. |  |
| ACCESS\_LOGS\_ENABLED | access\_logs.enabled |  | Enable the access logs. The access logs are used to log the incoming requests. By default, the access logs are enabled and logged to the standard output. | true |
| ACCESS\_LOGS\_LEVEL | access\_logs.level |  | Minimum level required for an access log entry to be emitted. One of: `debug`, `info`, `warn`, `error`, `panic`, `fatal`. | info |
| ACCESS\_LOGS\_ADD\_STACKTRACE | access\_logs.add\_stacktrace |  | When true, include stack traces in access logs for error cases. Panics always include stack traces regardless. | false |
|  | access\_logs.buffer |  | The buffer is used to buffer the logs before writing them to the output. |  |
| ACCESS\_LOGS\_BUFFER\_ENABLED | access\_logs.buffer.enabled |  | Enable the buffer. | false |
| ACCESS\_LOGS\_BUFFER\_SIZE | access\_logs.buffer.size |  | The size of the buffer. The default value is 256KB. |  |
| ACCESS\_LOGS\_FLUSH\_INTERVAL | access\_logs.buffer.flush\_interval |  | The interval at which the buffer is flushed. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’. |  |
|  | access\_logs.output |  | The log destination. The supported destinations are stdout and file. Only one option can be enabled. The default destination is stdout. |  |
| ACCESS\_LOGS\_OUTPUT\_STDOUT\_ENABLED | access\_logs.output.stdout.enabled |  |  | true |
| ACCESS\_LOGS\_OUTPUT\_FILE\_ENABLED | access\_logs.output.file.enabled |  |  | false |
| ACCESS\_LOGS\_FILE\_OUTPUT\_PATH | access\_logs.output.file.path |  | The path to the log file. The path is used to specify the path to the log file. |  |
| ACCESS\_LOGS\_FILE\_OUTPUT\_MODE | access\_logs.output.file.mode |  | The file mode (permissions) for the log file as an octal string. Must be exactly 3 octal digits (0-7), optionally prefixed with ‘0’ (e.g., ‘640’, ‘0640’, ‘755’, ‘0755’). The default value is ‘0640’. |  |
|  | access\_logs.router |  | The configuration for access logs for the router. |  |
| ACCESS\_LOGS\_ROUTER\_FIELDS | access\_logs.router.fields |  | The fields to add to the access logs for router. The fields are added to the logs as key-value pairs. | \[\] |
|  | access\_logs.router.fields.key |  | The key of the field to add to the logs. |  |
|  | access\_logs.router.fields.default |  | The default value of the field. If the value is not set, value\_from is used. If both value and value\_from are set, value\_from has precedence and in case of a missing value\_from, the default value is used. |  |
|  | access\_logs.router.value\_from |  | Defines a source for the field value e.g. from a request header. If both default and value\_from are set, value\_from has precedence. |  |
|  | access\_logs.router.value\_from.request\_header |  | The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used. |  |
|  | access\_logs.router.value\_from.context\_field |  | The field name of the context from which to extract the value. The value is only extracted when a context is available otherwise the default value is used. **One of:** \[ “operation\_name”, “operation\_type”, “operation\_service\_names”, “operation\_hash”, “persisted\_operation\_sha256”, “operation\_sha256”, “response\_error\_message”, “graphql\_error\_codes”, “graphql\_error\_service\_names”, “operation\_parsing\_time”, “operation\_validation\_time”, “operation\_planning\_time”, “operation\_normalization\_time” \] |  |
| ACCESS\_LOGS\_ROUTER\_IGNORE\_QUERY\_PARAMS\_LIST | access\_logs.router.ignore\_query\_params\_list |  | A list of query parameter names to ignore/exclude from the query field in access logs. This is useful for filtering out sensitive information from query parameters, especially when GraphQL requests are made over GET. | \[“variables”\] |
|  | access\_logs.subgraphs |  | The subgraph access logs configuration |  |
| ACCESS\_LOGS\_SUBGRAPH\_ENABLED | access\_logs.subgraphs.enabled |  | Enable the subgraphs access logs. | false |
| ACCESS\_LOGS\_SUBGRAPH\_FIELDS | access\_logs.subgraphs.fields |  | The fields to add to the logs when printing subgraph access logs. The fields are added to the logs as key-value pairs. |  |
|  | access\_logs.subgraphs.fields.key |  | The key of the field to add to the logs. |  |
|  | access\_logs.subgraphs.fields.default |  | The default value of the field. If the value is not set, value\_from is used. If both value and value\_from are set, value\_from has precedence and in case of a missing value\_from, the default value is used. |  |
|  | access\_logs.subgraphs.value\_from |  | Defines a source for the field value e.g. from a request header. If both default and value\_from are set, value\_from has precedence. |  |
|  | access\_logs.subgraphs.value\_from.request\_header |  | The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used. |  |
|  | access\_logs.subgraphs.value\_from.response\_header |  | The name of the response header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used. |  |
|  | access\_logs.subgraphs.value\_from.context\_field |  | The field name of the context from which to extract the value. The value is only extracted when a context is available otherwise the default value is used. **One of:** \[ “operation\_name”, “operation\_type”, “operation\_hash”, “persisted\_operation\_sha256”, “operation\_sha256”, “operation\_parsing\_time”, “operation\_validation\_time”, “operation\_planning\_time”, “operation\_normalization\_time” \] |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config)  Example YAML config:

config.yaml

```
version: "1"

access_logs:
  enabled: true
  level: info
  add_stacktrace: true
  buffer:
    enabled: false
    size: 256KB
    flush_interval: 10s
  output:
    file:
      enabled: true
      path: "access.log"
      mode: "0640"
  router:
    ignore_query_params_list:
      - "extensions"
    fields:
      - key: "service"
        value_from:
          request_header: "x-service"
      - key: "operationName"
        value_from:
          context_field: operation_name
  subgraphs:
    fields:
      - key: "service"
        value_from:
          request_header: "x-service"
      - key: "response-service"
        value_from:
          response_header: "x-response-service"
      - key: "operationName"
        value_from:
          context_field: operation_name
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#telemetry)  Telemetry

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#graph)  Graph

Overall configuration for the Graph that’s configured for this Router.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| GRAPH\_API\_TOKEN | token |  | The token permits the router to communicate with the controlplane and export telemetry. Created with . (Can be empty when providing a static router configuration through `ROUTER_CONFIG_PATH`but will disable the default telemetry stack) |  |

Example YAML config:

config.yaml

```
version: "1"

graph:
  token: "<your-graph-token>"
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#introspection)  Introspection

Overall configuration for managing introspection queries on this Router.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| INTROSPECTION\_ENABLED | enabled |  | Enable or disable introspection queries | true |
| INTROSPECTION\_SECRET | secret |  | Optional, dedicated secret used for instrospection authentication. Only used when `authentication.ignore_introspection` is set to `true`. |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-2)  Example YAML config:

config.yaml

```
version: "1"

introspection:
  enabled: true
  secret: "dedicated_secret_for_introspection"
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#mcp-model-context-protocol)  MCP (Model Context Protocol)

The Model Context Protocol (MCP) server allows AI models to discover and interact with your GraphQL API in a secure way.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| MCP\_ENABLED | mcp.enabled |  | Enable or disable the MCP server | false |
| MCP\_SERVER\_LISTEN\_ADDR | mcp.server.listen\_addr |  | The address and port where the MCP server will listen for requests | localhost:5025 |
| MCP\_ROUTER\_URL | mcp.router\_url |  | Custom URL to use for the router GraphQL endpoint in MCP. Use this when your router is behind a proxy; used in MCP responses to provide the real router URL. | - |
| MCP\_STORAGE\_PROVIDER\_ID | mcp.storage.provider\_id |  | The ID of a storage provider to use for loading GraphQL operations. Only file\_system providers are supported. | - |
| MCP\_SESSION\_STATELESS | mcp.session.stateless |  | Whether the MCP server should operate in stateless mode. When true, no server-side session state is maintained between requests. | true |
| MCP\_GRAPH\_NAME | mcp.graph\_name |  | The name of the graph this router exposes via MCP. Used to build the MCP server name (wundergraph-cosmo-$graph\_name) and for logging; it does not select a different graph. | mygraph |
| MCP\_EXCLUDE\_MUTATIONS | mcp.exclude\_mutations |  | Whether to exclude mutation operations from being exposed | false |
| MCP\_ENABLE\_ARBITRARY\_OPERATIONS | mcp.enable\_arbitrary\_operations |  | Whether to allow arbitrary GraphQL operations to be executed. <br>Security risk: Should only be enabled in secure, internal environments. | false |
| MCP\_EXPOSE\_SCHEMA | mcp.expose\_schema |  | Whether to expose the full GraphQL schema. <br>Security risk: Should only be enabled in secure, internal environments. | false |
| MCP\_OMIT\_TOOL\_NAME\_PREFIX | mcp.omit\_tool\_name\_prefix |  | When enabled, MCP tool names generated from GraphQL operations omit the `execute_operation_` prefix. | false |

Example YAML config:

config.yaml

```
version: "1"

mcp:
  enabled: true
  server:
    listen_addr: "localhost:5025"
  router_url: "https://your-public-router-url.example.com/graphql" # Optional: Used in MCP responses when your router is behind a proxy.
  storage:
    provider_id: "mcp" # References a file_system provider defined below
  session:
    stateless: true # Optional: When true, no server-side session state is kept
  graph_name: "my-graph"
  exclude_mutations: true
  enable_arbitrary_operations: false
  expose_schema: false

# Configure storage providers
storage_providers:
  file_system:
    - id: "mcp"
      path: "operations" # Relative to the router binary
```

For more details on how to use the MCP server, see the [MCP Integration documentation](https://cosmo-docs.wundergraph.com/router/mcp).

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#tls)  TLS

The Router supports TLS and mTLS for secure communication with your clients and infrastructure components like load balancer.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#server-tls)  Server TLS

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| TLS\_SERVER\_ENABLED | enabled |  | Enables server TLS support. | false |
| TLS\_SERVER\_CERT\_FILE | cert\_file |  | The path to the server certificate file. |  |
| TLS\_SERVER\_KEY\_FILE | key\_file |  | The path to the server private key file. |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-3)  Example YAML config:

config.yaml

```
version: "1"

tls:
  server:
    enabled: true
    key_file: ../your/key.pem
    cert_file: ../your/cert.pem
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#client-authentication)  Client Authentication

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| TLS\_CLIENT\_AUTH\_CERT\_FILE | cert\_file |  | Enables client authentication support. The file to the certificate file used to authenthicate clients. | ” “ |
| TLS\_CLIENT\_AUTH\_REQUIRED | required |  | Enforces a valid client certificate to establish a connection. | false |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-4)  Example YAML config:

config.yaml

```
version: "1"

tls:
  server:
    enabled: true # Required for client_auth
    key_file: ../your/key.pem
    cert_file: ../your/cert.pem
    client_auth:
      required: true
      cert_file: ../your/cert.pem
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#outbound-tls-to-subgraphs)  Outbound TLS to Subgraphs

Configure TLS for outbound connections from router to subgraphs.
See [TLS](https://cosmo-docs.wundergraph.com/router/security/tls) for details.

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#http-subgraphs)  HTTP Subgraphs

Configuring a subgraph URL with a `https://` scheme activates TLS to subgraphs.
Specifying `ca_file` additionally verifies a subgraphs certificate against that CA certificate.

Additionally specifying `cert_file` and `key_file` enables mTLS on subgraph connections.The following settings configure TLS for HTTP based subgraphs.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| TLS\_CLIENT\_ALL\_CA\_FILE | tls.client.all.ca\_file |  | Path to a custom CA certificate file for verifying subgraph server certificates. |  |
| TLS\_CLIENT\_ALL\_CERT\_FILE | tls.client.all.cert\_file |  | Path to the client certificate chain file for authenticating the router to subgraphs. Enables mTLS. |  |
| TLS\_CLIENT\_ALL\_KEY\_FILE | tls.client.all.key\_file |  | Path to the client private key file. Enables mTLS. |  |
| TLS\_CLIENT\_ALL\_INSECURE\_SKIP\_CA\_VERIFICATION | tls.client.all.insecure\_skip\_ca\_verification |  | Skip verification of the subgraph server certificate. Only use for development or testing. | false |

##### Example YAML config:

config.yaml

```
version: "1"

tls:
  client:
    all: # global tls configuration affecting all HTTP subgraphs
      cert_file: /path/to/client.crt
      key_file: /path/to/client.key
      ca_file: /path/to/ca.crt
    subgraphs: # additional overwrites for specific HTTP subgraphs
      products:
        cert_file: /path/to/products-client.crt
        key_file: /path/to/products-client.key
```

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#grpc-subgraphs)  gRPC Subgraphs

The configuration settings above are not applied to gRPC subgraphs.
For gRPC subgraphs, TLS must be explicitly enabled with `enabled: true`.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| TLS\_CLIENT\_GRPC\_ALL\_ENABLED | tls.client\_grpc.all.enabled |  | Enable TLS for all gRPC subgraph connections. |  |
| TLS\_CLIENT\_GRPC\_ALL\_CA\_FILE | tls.client\_grpc.all.ca\_file |  | Path to a custom CA certificate file for verifying gRPC subgraph server certificates. |  |
| TLS\_CLIENT\_GRPC\_ALL\_CERT\_FILE | tls.client\_grpc.all.cert\_file |  | Path to the client certificate chain file for authenticating the router to gRPC subgraphs. Enables mTLS. |  |
| TLS\_CLIENT\_GRPC\_ALL\_KEY\_FILE | tls.client\_grpc.all.key\_file |  | Path to the client private key file. Enables mTLS. |  |
| TLS\_CLIENT\_GRPC\_ALL\_INSECURE\_SKIP\_CA\_VERIFICATION | tls.client\_grpc.all.insecure\_skip\_ca\_verification |  | Skip verification of the gRPC subgraph server certificate. Only use for development or testing. | false |

##### Example YAML config:

config.yaml

```
version: "1"

tls:
  client_grpc:
    all: # global TLS configuration for all gRPC subgraphs
      enabled: true
      cert_file: /path/to/client.crt
      key_file: /path/to/client.key
      ca_file: /path/to/ca.crt
    subgraphs: # per-subgraph overrides
      products:
        enabled: true
        cert_file: /path/to/products-client.crt
        key_file: /path/to/products-client.key
      projects:
        enabled: false # specifically disable TLS for this subgraph
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#compliance)  Compliance

The configuration for the compliance. Includes for example the configuration for the anonymization of the IP addresses.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#ip-anonymization)  IP Anonymization

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| SECURITY\_ANONYMIZE\_IP\_ENABLED | enabled |  | Enables IP anonymization in traces and logs. | true |
| SECURITY\_ANONYMIZE\_IP\_METHOD | method |  | The metod to anonymize IP addresses. Can be “hash” or “redact”. | “redact” |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-5)  Example YAML config:

config.yaml

```
version: "1"

compliance:
  anonymize_ip:
    enabled: true
    method: redact # hash or redact
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#cluster)  Cluster

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| CLUSTER\_NAME | name |  | The logical name of the router cluster. The name is used for analytic purpose. |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-6)  Example YAML config:

config.yaml

```
version: "1"

# See "https://cosmo-docs.wundergraph.com/studio/cluster-management" for more information
cluster:
  name: "us-central1-cosmo-cloud "
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#telemetry-2)  Telemetry

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| TELEMETRY\_SERVICE\_NAME | service\_name |  | The name of the service. | cosmo-router |
|  | resource\_attributes |  | The resource attributes to add to OTEL metrics and traces. The resource attributes identify the entity producing the traces and metrics. |  |
|  | resource\_attributes.key |  | The key of the attribute. |  |
|  | resource\_attributes.value |  | The value of the attribute. |  |
|  | attributes |  | The attributes to add to OTEL metrics and traces. Because Prometheus metrics rely on the OpenTelemetry metrics, the attributes are also added to the Prometheus metrics. | \[\] |
|  | attributes.key |  | The key of the attribute. |  |
|  | attributes.default |  | The value of the attribute. |  |
|  | attributes.value\_from |  | Defines a source for the attribute value e.g. from a request header. If both default and value\_from are set, value\_from has precedence. |  |
|  | attributes.value\_from.request\_header |  | The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used. Don’t forget to add the header to your CORS settings. |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-7)  Example YAML config:

config.yaml

```
version: "1"

# Only needed when setting attributes based on a request header
cors:
  allow_headers:
    - "x-service"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # Common options
  service_name: "cosmo-router"
  resource_attributes:
    - key: env
      value: "prod"
  attributes:
    - key: service
      default: "static"
      value_from:
        request_header: "x-service"
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#tracing)  Tracing

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| TRACING\_ENABLED | enabled |  |  | true |
| TRACING\_SAMPLING\_RATE | sampling\_rate |  | The sampling rate for the traces. The value must be between 0 and 1. If the value is 0, no traces will be sampled. If the value is 1, all traces will be sampled. For managed plans, the trace sampling rate will not exceed the rate imposed by the organization limit of the plan. | 1 |
| TRACING\_PARENT\_BASED\_SAMPLER | parent\_based\_sampler |  | Enable the parent-based sampler. The parent-based sampler is used to sample the traces based on the parent trace. | true |
| TRACING\_BATCH\_TIMEOUT | batch\_timeout |  | The maximum delay allowed before spans are exported. | 10s |
| TRACING\_EXPORT\_GRAPHQL\_VARIABLES | export\_graphql\_variables |  | Export GraphQL variables as span attribute. Variables may contain sensitive data. | false |
| TRACING\_OPERATION\_CONTENT\_ATTRIBUTES | operation\_content\_attributes |  | Enable the addition of GraphQL operation body content as trace attributes. When enabled, original operation content will be added to the trace span for parse and normalized operation content will be added to the trace span for normalize. The default value is false. | false |
|  | with\_new\_root |  | Starts the root span always at the router. | false |
| TRACING\_SANITIZE\_UTF8\_ENABLED | sanitize\_utf8.enabled |  | Enable sanitization of invalid UTF-8 sequences in span attribute values. Invalid bytes are replaced with the Unicode replacement character (U+FFFD). See [Sanitize UTF-8](https://cosmo-docs.wundergraph.com/router/open-telemetry#sanitize-utf-8). | false |
| TRACING\_SANITIZE\_UTF8\_LOG\_SANITIZATIONS | sanitize\_utf8.log\_sanitizations |  | When enabled, logs a warning for each span attribute that contains invalid UTF-8 and is sanitized. | false |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-8)  Example YAML config:

config.yaml

```
version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # Common options
  service_name: "cosmo-router"
  # uses https://cosmo-otel.wundergraph.com for tracing and metrics

# OpenTelemetry Tracing
  tracing:
    enabled: true
    sampling_rate: 1
    batch_timeout: "10s"
    export_graphql_variables: false
    operation_content_attributes: false
    with_new_root: false
    sanitize_utf8:
      enabled: false
      log_sanitizations: false
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#exporters)  Exporters

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | diabled |  | bool |  |
|  | exporter |  | one of: http,grpc |  |
|  | endpoint |  |  |  |
|  | path |  |  |  |
|  | headers |  |  |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-9)  Example YAML config:

config.yaml

```
version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  tracing:
    enabled: true
    exporters:
      # If no exporters are defined, the default one is used
      - exporter: http # or grpc
        disabled: false
        endpoint: https://my-otel-collector.example.com
        # headers: {Authorization: Bearer <my-token>}
        batch_timeout: 10s
        export_timeout: 30s
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#propagation)  Propagation

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | trace\_context |  |  | true |
|  | jaeger |  |  |  |
|  | b3 |  |  |  |
|  | baggage |  |  |  |
|  | datadog |  | Enable Datadog trace propagation | false |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-10)  Example YAML config:

config.yaml

```
version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # OpenTelemetry Tracing
  tracing:
    propagation:
      # https://www.w3.org/TR/trace-context/
      trace_context: true
      # https://www.w3.org/TR/baggage/
      baggage: false
      # https://www.jaegertracing.io/ (compliant with opentracing)
      jaeger: false
      # https://github.com/openzipkin/b3-propagation (zipkin)
      b3: false
      # https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation/?tab=java#datadog-format
      datadog: false
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#attributes)  Attributes

| YAML | Required | Description | Default Value |
| --- | --- | --- | --- |
| attributes |  | The attributes to add for Tracing. | \[\] |
| attributes.key |  | The key of the field. |  |
| attributes.value\_from |  | Defines a source for the field value. |  |
| attributes.value\_from.expression |  | The expression for the trace attribute. |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-11)  Example YAML config:

config.yaml

```
version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  # OpenTelemetry Tracing
  tracing:
    attributes:
      - key: "x-new-attribute"
        value_from:
          expression: "request.url.method"
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#metrics)  Metrics

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| METRICS\_EXPERIMENT\_CARDINALITY\_LIMIT | experiment\_cardinality\_limit |  | Sets a hard limit on the number of Metric Points that can be collected during a collection cycle. | 2000 |

The `experiment_cardinality_limit` option is experimental because it relies on experimental functionality in the OpenTelemetry SDK for Go. This feature helps prevent excessive memory usage by limiting the number of unique metric combinations (cardinality) that can be collected in a single collection cycle.See the specification for more information: [https://opentelemetry.io/docs/specs/otel/metrics/sdk/#cardinality-limits](https://opentelemetry.io/docs/specs/otel/metrics/sdk/#cardinality-limits)This option may change or be removed in future versions as the OpenTelemetry SDK stabilizes this functionality.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#otlp)  OTLP

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| METRICS\_OTLP\_ENABLED | enabled |  | Enables OTEL metrics instrumentation | true |
| METRICS\_OTLP\_ROUTER\_RUNTIME | router\_runtime |  | Enable the collection of metrics for the router runtime. | true |
| METRICS\_OTLP\_GRAPHQL\_CACHE | graphql\_cache |  | Enable the collection of metrics for the GraphQL operation router caches. | false |
| METRICS\_OTLP\_EXCLUDE\_METRICS | exclude\_metrics |  | The metrics to exclude from the OTEL metrics. Accepts a list of Go regular expressions. Use [https://regex101.com/](https://regex101.com/) to test your regular expressions. | \[\] |
| METRICS\_OTLP\_EXCLUDE\_METRIC\_LABELS | exclude\_metric\_labels |  | The metric labels to exclude from the OTEL metrics. Accepts a list of Go regular expressions. Use [https://regex101.com/](https://regex101.com/) to test your regular expressions. | \[\] |
| METRICS\_OTLP\_CONNECTION\_STATS | connection\_stats |  | Enable connection metrics. | false |
| METRICS\_OTLP\_NETWORK\_ENABLED | network.enabled |  | Enable per-request subgraph HTTP phase metrics: DNS lookup, TCP connect, TLS handshake, time-to-first-request-byte, and time-to-first-byte histograms. | false |
| METRICS\_OTLP\_RESOLVER\_ENABLED | resolver.enabled |  | Enable resolver metrics: resolver concurrency gauges and the resolver acquire duration histogram. | false |
| METRICS\_OTLP\_CIRCUIT\_BREAKER | circuit\_breaker |  | Ensure that circuit breaker metrics are enabled for OTEL. | false |
| METRICS\_OTLP\_STREAM | streams |  | Enable Cosmo Streams metrics. | false |
| METRICS\_OTLP\_EXEMPLAR\_FILTER | exemplar\_filter |  | Controls which measurements are eligible to record exemplars. One of: `always_off`, `trace_based`, `always_on`. See [Exemplars](https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring/exemplars). | always\_off |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#metrics-log-exporter)  Metrics Log Exporter

Configured under `telemetry.metrics.otlp.log_exporter`. See [Metrics Log Exporter](https://cosmo-docs.wundergraph.com/router/open-telemetry#metrics-log-exporter) for details.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| METRICS\_OTLP\_LOG\_EXPORTER\_ENABLED | enabled |  | Enable the metrics log exporter. | false |
| METRICS\_OTLP\_LOG\_EXPORTER\_EXCLUDE\_METRICS | exclude\_metrics |  | List of Go regex patterns. Metrics matching any pattern will not be logged. Cannot be used together with `include_metrics`. | \[\] |
| METRICS\_OTLP\_LOG\_EXPORTER\_INCLUDE\_METRICS | include\_metrics |  | List of Go regex patterns. When set, only metrics matching at least one pattern are logged. Cannot be used with `exclude_metrics`. | \[\] |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#attributes-2)  Attributes

| YAML | Required | Description | Default Value |
| --- | --- | --- | --- |
| attributes |  | The attributes to add to OTLP Metrics and Prometheus. | \[\] |
| attributes.key |  | The key of the field. |  |
| attributes.default |  | The default value of the field. If the value is not set, value\_from is used. If both value and value\_from are set, value\_from has precedence and in case of a missing value\_from, the default value is used. |  |
| attributes.value\_from |  | Defines a source for the field value e.g. from a request header or request context. If both default and value\_from are set, value\_from has precedence. |  |
| attributes.value\_from.request\_header |  | The name of the request header from which to extract the value. The value is only extracted when a request context is available otherwise the default value is used. |  |
| attributes.value\_from.context\_field |  | The field name of the context from which to extract the value. The value is only extracted when a context is available otherwise the default value is used. | One of:\[“operation\_service\_names”, “graphql\_error\_codes”, “graphql\_error\_service\_names”, “operation\_sha256”\] |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-12)  Example YAML config:

config.yaml

```
# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  metrics:
    experiment_cardinality_limit: 2000
    otlp:
      enabled: true
      router_runtime: true
      graphql_cache: true
      connection_stats: false
      # Per-request subgraph HTTP phase metrics (DNS, TCP connect, TLS handshake, time to first request byte, time to first byte)
      network:
        enabled: false
      # Resolver concurrency gauges and resolver acquire duration histogram
      resolver:
        enabled: false
      exclude_metrics: []
      exclude_metric_labels: []
      streams: true
      # Record exemplars only for measurements taken within a sampled trace.
      # One of: always_off (default), trace_based, always_on
      exemplar_filter: always_off
      log_exporter:
        enabled: false
        # note that both exclude_metrics and include_metrics cannot be used together
        exclude_metrics: []
        include_metrics: []
    attributes:
      - key: "x-new-attribute"
        default: "foo"
        value_from:
          request_header: "X-Request-ID"

- key: "error_codes"
        value_from:
          context_field: graphql_error_codes
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#prometheus)  Prometheus

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| PROMETHEUS\_ENABLED | enabled |  | Enables prometheus metrics support | true |
| PROMETHEUS\_HTTP\_PATH | path |  | The HTTP path where metrics are exposed. | ”/metrics” |
| PROMETHEUS\_LISTEN\_ADDR | listen\_addr |  | The address to listen on for the prometheus metrics endpoint. | ”127.0.0.1:8088” |
| PROMETHEUS\_GRAPHQL\_CACHE | graphql\_cache |  | Enable the collection of metrics for the GraphQL operation router caches. | false |
| PROMETHEUS\_CONNECTION\_STATS | connection\_stats |  | Enable connection metrics. | false |
| PROMETHEUS\_NETWORK\_ENABLED | network.enabled |  | Enable per-request subgraph HTTP phase metrics: DNS lookup, TCP connect, TLS handshake, time-to-first-request-byte, and time-to-first-byte histograms. | false |
| PROMETHEUS\_RESOLVER\_ENABLED | resolver.enabled |  | Enable resolver metrics: resolver concurrency gauges and the resolver acquire duration histogram. | false |
| PROMETHEUS\_EXCLUDE\_METRICS | exclude\_metrics |  |  |  |
| PROMETHEUS\_EXCLUDE\_METRIC\_LABELS | exclude\_metric\_labels |  |  |  |
| PROMETHEUS\_EXCLUDE\_SCOPE\_INFO | exclude\_scope\_info |  | Exclude scope info from Prometheus metrics. | false |
| PROMETHEUS\_CIRCUIT\_BREAKER | circuit\_breaker |  | Enable the circuit breaker metrics for prometheus metric collection. | false |
| PROMETHEUS\_OTLP\_STREAM | streams |  | Enable Cosmo Streams metrics. | false |
| PROMETHEUS\_EXEMPLAR\_FILTER | exemplar\_filter |  | Controls which measurements are eligible to record exemplars. One of: `always_off`, `trace_based`, `always_on`. See [Exemplars](https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring/exemplars). | always\_off |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-13)  Example YAML config:

config.yaml

```
version: "1"

# See "https://cosmo-docs.wundergraph.com/router/metrics-and-monitoring" for more information
telemetry:
  metrics:
    # Expose OpenTelemetry metrics for scraping
    prometheus:
      enabled: true
      path: "/metrics"
      listen_addr: "127.0.0.1:8088"
      graphql_cache: true
      connection_stats: false
      # Per-request subgraph HTTP phase metrics (DNS, TCP connect, TLS handshake, time to first request byte, time to first byte)
      network:
        enabled: false
      # Resolver concurrency gauges and resolver acquire duration histogram
      resolver:
        enabled: false
      exclude_metrics: []
      exclude_metric_labels: []
      streams: true
      exclude_scope_info: false
      # Record exemplars only for measurements taken within a sampled trace.
      # One of: always_off (default), trace_based, always_on
      exemplar_filter: always_off
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#exporter)  Exporter

| YAML | Required | Description | Default Value |
| --- | --- | --- | --- |
| disabled |  |  |  |
| exporter |  | one of: http,grpc |  |
| endpoint |  |  |  |
| path |  | The path to which the metrics are exported. This is ignored when using ‘grpc’ as exporter and can be omitted. |  |
| headers |  |  |  |
| temporality |  | Temporality defines the window that an aggregation is calculated over. one of: delta, cumulative |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-14)  Example YAML config:

config.yaml

```
version: "1"

# OpenTelemetry Metrics
  metrics:
    otlp:
      enabled: true
      # If no exporters are defined, the default one is used
      exporters:
        - exporter: http # or grpc
          disabled: false
          endpoint: https://my-otel-collector.example.com
          temporality: delta # or cumulative
          # headers: {Authorization: Bearer <my-token>}
      log_exporter:
        enabled: false
        # note that both exclude_metrics and include_metrics cannot be used together
        exclude_metrics: []
        include_metrics: []

# Expose OpenTelemetry metrics for scraping
    prometheus:
      enabled: true
      path: "/metrics"
      listen_addr: "127.0.0.1:8088"
      exclude_metrics: []
      exclude_metric_labels: []
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#graphql-metrics)  GraphQL Metrics

The router collects GraphQL schema usage metrics, which are the types, fields, and arguments each client operation uses, and sends them to the Cosmo GraphQL Metrics collector. This data powers [field-level analytics](https://cosmo-docs.wundergraph.com/studio/analytics/schema-field-usage) and [breaking-change detection](https://cosmo-docs.wundergraph.com/studio/schema-checks). Set `enabled` to `false` (or `GRAPHQL_METRICS_ENABLED=false`) to stop the router from collecting and sending this data.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| GRAPHQL\_METRICS\_ENABLED | enabled |  | Enable collection and export of GraphQL schema usage metrics (field-level usage) to the collector. Set to `false` to disable. | true |
| GRAPHQL\_METRICS\_COLLECTOR\_ENDPOINT | collector\_endpoint |  | Endpoint of the GraphQL Metrics collector that receives schema usage data. Self-hosted deployments point this at their own collector. | [https://cosmo-metrics.wundergraph.com](https://cosmo-metrics.wundergraph.com/) |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-15)  Example YAML config:

config.yaml

```
version: "1"

graphql_metrics:
  enabled: true
  collector_endpoint: "https://cosmo-metrics.wundergraph.com"
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#pyroscope-continuous-profiling)  Pyroscope (Continuous Profiling)

Continuously profile the router with [Grafana Pyroscope](https://grafana.com/oss/pyroscope/). When enabled, the router periodically collects profiles (CPU, memory, and more) and uploads them to a Pyroscope server, so you can analyze the router’s performance over time in Grafana. This works against a self-hosted Pyroscope instance or [Grafana Cloud Profiles](https://grafana.com/products/cloud/profiles/). See the [Profiling guide](https://cosmo-docs.wundergraph.com/router/profiling#continuous-profiling-with-grafana-pyroscope) for a walkthrough.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| PYROSCOPE\_ENABLED | enabled |  | Enable continuous profiling. When enabled, `server_address` must be set. | false |
| PYROSCOPE\_SERVER\_ADDRESS | server\_address | (when enabled) | Address of the Pyroscope server the profiles are sent to, e.g. your own Pyroscope or a Grafana Cloud instance. |  |
| PYROSCOPE\_APPLICATION\_NAME | application\_name |  | Application name the profiles are stored under. | wundergraph.cosmo.router |
| PYROSCOPE\_BASIC\_AUTH\_USERNAME | basic\_auth.username |  | Username for basic authentication. For Grafana Cloud, this is the stack user ID. |  |
| PYROSCOPE\_BASIC\_AUTH\_PASSWORD | basic\_auth.password |  | Password for basic authentication. For Grafana Cloud, this is an access token with profile write permissions. |  |
| PYROSCOPE\_HEADERS | headers |  | Map of headers to send with each profile upload request, e.g. to authenticate with a bearer token instead of basic auth. As an environment variable, use the format `key1:value1,key2:value2`. |  |
| PYROSCOPE\_TAGS | tags |  | Map of static tags attached to all profiles. The router always attaches the hostname and router version as tags. As an environment variable, use the format `key1:value1,key2:value2`. |  |
| PYROSCOPE\_UPLOAD\_RATE | upload\_rate |  | Interval at which profiles are uploaded to the Pyroscope server (e.g. `15s`, `1m`). | 15s |
| PYROSCOPE\_PROFILE\_TYPES | profile\_types |  | Profile types to collect. Valid values: `cpu`, `alloc_objects`, `alloc_space`, `inuse_objects`, `inuse_space`, `goroutines`, `mutex_count`, `mutex_duration`, `block_count`, `block_duration`, `goroutine_leak`. Unrecognized values are ignored. | cpu, alloc\_objects, alloc\_space, inuse\_objects, inuse\_space |
| PYROSCOPE\_DISABLE\_GC\_RUNS | disable\_gc\_runs |  | Disable the automatic `runtime.GC` run before each heap profile upload. Enabling this avoids extra GC pauses on large-heap or latency-sensitive routers, at the cost of less accurate memory profiles. | false |
| PYROSCOPE\_MUTEX\_PROFILE\_FRACTION | mutex\_profile\_fraction |  | Fraction of mutex contention events reported in the mutex profile; on average 1/n events are reported. Set to `0` to disable mutex profiling. | 5 |
| PYROSCOPE\_BLOCK\_PROFILE\_RATE | block\_profile\_rate |  | Fraction of goroutine blocking events reported in the block profile; on average 1/n events are reported. Set to `0` to disable block profiling. | 5 |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-16)  Example YAML config:

config.yaml

```
version: "1"

pyroscope:
  enabled: true
  server_address: "http://localhost:4040"
  application_name: "wundergraph.cosmo.router"
  # Optional: authenticate against Grafana Cloud
  basic_auth:
    username: "<stack-user-id>"
    password: "<access-token>"
  tags:
    env: "production"
  upload_rate: 15s
  profile_types:
    - cpu
    - alloc_objects
    - alloc_space
    - inuse_objects
    - inuse_space
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#cors)  CORS

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| CORS\_ENABLED | enabled |  | Set this to enable/disable the CORS middleware. It is enabled by default. When disabled, the rest of the properties for CORS have no effect. | true |
| CORS\_ALLOW\_ORIGINS | allow\_origins |  | This is a list of origins which are allowed. You can provide origins with wildcards | \* |
| CORS\_ALLOW\_METHODS | allow\_methods |  |  | HEAD,GET,POST |
| CORS\_ALLOW\_HEADERS | allow\_headers |  |  | Origin, Content-Length, Content-Type |
| CORS\_ALLOW\_CREDENTIALS | allow\_credentials |  |  | true |
| CORS\_MAX\_AGE | max\_age |  |  | 5m |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-17)  Example YAML config:

config.yaml

```
version: "1"

cors:
  allow_origins: ["*"]
  allow_methods:
    - HEAD
    - GET
    - POST
  allow_headers:
    - Origin
    - Content-Length
    - Content-Type
  allow_credentials: true
  max_age: 5m
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#cache-control-policy)  Cache Control Policy

Configure your cache control policy. More information on this feature can be found here: [#cache-control-policy](https://cosmo-docs.wundergraph.com/router/proxy-capabilities#cache-control-policy)

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| CACHE\_CONTROL\_POLICY\_ENABLED | enabled |  | Set this to enable/disable the strict cache control policy. It is false by default | false |
| CACHE\_CONTROL\_POLICY\_VALUE | value |  | The default value for the cache control policy. It will be applied to all requests, unless a subgraph has a more strict one |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-18)  Example YAML Config:

config.yaml

```
version: "1"

cache_control_policy:
  enabled: true
  value: "max-age=180, public"
  subgraphs:
    - name: "products"
      value: "max-age=60, public"
    - name: "pricing"
      value: "no-cache"
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#custom-modules)  Custom Modules

Configure your custom Modules. More information on this feature can be found here: [Custom Modules](https://cosmo-docs.wundergraph.com/router/custom-modules)

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-19)  Example YAML config:

config.yaml

```
version: "1"

modules:
  myModule:
    # Arbitrary values, unmarshalled by the module
    value: 1
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#router-plugins)  Router Plugins

The configuration for the router plugins. To learn more about the plugins, see the [plugins documentation](https://cosmo-docs.wundergraph.com/router/gRPC/plugins).

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| PLUGINS\_ENABLED | enabled |  | Enable the router plugins. If the value is true, the router plugins are enabled. | false |
| PLUGINS\_PATH | path |  | The path to the plugins directory. The plugins directory is used to load the plugins. | plugins |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-20)  Example YAML config:

config.yaml

```
version: "1"

plugins:
  enabled: true
  path: "plugins"
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#headers)  Headers

Configure Header propagation rules for all Subgraphs or individual Subgraphs by name.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#cookie-whitelist)  Cookie Whitelist

When `Cookie`is a propagated header, you may want to filter the keys that are forwarded to the subgraph from the client, you can do this via the `cookie_whitelist`option, which is a list of string cookie keys that will not be discarded. An empty value means allow all. If you’d like to block all cookies, disable the header propagation entirely.

The cookie whitelist can also affect custom modules that read request cookies,
even if propagation is disabled for the `Cookie` header. This is because the
whitelisting happens very early in the request lifecycle, before it reaches
subgraphs or custom modules.

**Example YAML config:**

```
version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more info
headers:
  cookie_whitelist:
   - "authorization"
   - "my-cookie-key"
  all:
    request:
      - op: "propagate"
        named: Cookie
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#global-header-rules)  Global Header Rules

Apply to requests/responses to/from “all” Subgraphs. These will be applied globally in the graph

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | request |  | List of Request Header Rules |  |
|  | response |  | List of Response Header Rules |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-21)  Example YAML config:

config.yaml

```
version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more info
headers:
  all: # Header rules for all origin requests.
    request:
      - op: "propagate"
        named: X-Test-Header
      - op: "propagate"
        matching: (?i)^x-deprecated-.*
      - op: "set"
        name: "X-API-Key"
        value: "my-secret-value"
    response:
      - op: "propagate"
        algorithm: "append"
        named: "X-Custom-Header"
```

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#header-rule-example-using-template-expression)  Header Rule Example Using Template Expression:

This example sets the `X-User-ID` header based on the `sub` claim from the JWT token, if the user is authenticated.
Learn more about [template expressions](https://cosmo-docs.wundergraph.com/router/configuration/template-expressions).

config.yaml

```
version: "1"

headers:
  all:
    request:
      - op: "set"
        name: "X-User-ID"
        # Sets the header only if the user is authenticated
        expression: "request.auth.isAuthenticated ? request.auth.claims.sub : ''"
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#request-header-rule)  Request Header Rule

Apply to requests to specific Subgraphs.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | op |  | oneof=propagate, set |  |
|  | matching |  | matching is the regex to match the header name against |  |
|  | named |  | named is the exact header name to match |  |
|  | rename |  | renames the header’s key to the provided value |  |
|  | default |  | default is the default value to set if the header is not present |  |
|  | name |  | If `op` is `set`, `name` is the name of the desired header to set |  |
|  | value |  | If `op` is `set`, `value` is the value of the desired header to set |  |
|  | expression |  | If `op` is `set`, `expression` is the [expression](https://cosmo-docs.wundergraph.com/router/configuration/template-expressions) to evaluate to get the value of the desired header to set |  |
|  | from\_file |  | If `op` is `set`, sources the header value from a file’s contents. The file is loaded into memory and refreshed on a polling interval, so request-time reads do not touch disk. Request rules only. |  |
|  | from\_file.path |  | Absolute path to the file whose contents become the header value. |  |
|  | from\_file.refresh\_interval |  | Determines how often the file is checked for changes and re-read into memory. The minimum value is `100ms`. | `1m` |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-22)  Example YAML config:

config.yaml

```
version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more information
headers:
  subgraphs:
    product: # Header rules for the "product" Subgraph
      request:
        - op: "propagate"
          named: X-Test-Header
        - op: "set"
          name: "X-API-Key"
          value: "my-secret-value"
        # Read the value from a file. The file is loaded once at startup and
        # re-read every refresh_interval. Useful for mounted secrets that
        # rotate (e.g. Kubernetes Secrets, Vault Agent sidecars).
        - op: "set"
          name: "X-Service-Token"
          from_file:
            path: "/etc/secrets/service-token"
            refresh_interval: "1m"
```

`from_file` is request-only. It cannot be used in response header rules.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#response-header-rule)  Response Header Rule

These rules can be applied to all responses, as well as just to specific subgraphs, and used to manipulate and propagate response headers from subgraphs to the client. By configuring the rule, users can define how headers should be handled when multiple subgraphs provide conflicting values for a specific header.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | op |  | oneof=propagate, set |  |
|  | algorithm |  | oneof=first\_write, last\_write, append |  |
|  | matching |  | matching is the regex to match the header name against. This |  |
|  | named |  | named is the exact header name to match |  |
|  | default |  | default is the default value to set if the header is not present |  |
|  | rename |  | renames the header’s key to the provided value |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-23)  Example YAML config:

config.yaml

```
version: "1"

# Header manipulation
# See "https://cosmo-docs.wundergraph.com/router/proxy-capabilities" for more information
headers:
  subgraphs:
    product: # Header rules for the "product" Subgraph
      response:
        - op: "propagate"
          algorithm: "append"
          named: "X-Test-Header"
        - op: "propagate"
          algorithm: "last_write"
          named: "X-Test2-Header"
        - op: "set"
          name: "X-User-Key"
          value: "my-user-value"
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#storage-providers)  Storage Providers

Storage providers allow you to configure different backends for persisted operations, router execution config and MCP operations.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-24)  Example YAML config:

config.yaml

```
version: "1"

storage_providers:
  s3:
    - id: "s3-provider"
      endpoint: "s3.amazonaws.com"
      access_key: "${AWS_ACCESS_KEY_ID}"
      secret_key: "${AWS_SECRET_ACCESS_KEY}"
      bucket: "my-bucket"
      region: "us-east-1"
      secure: true
  redis:
    - id: "redis-provider"
      urls:
        - "redis://localhost:6379"
      cluster_enabled: false
  file_system:
    - id: "fs-provider"
      path: "/path/to/files"
  cdn:
    - id: "cdn-provider"
      url: "https://cosmo-cdn.wundergraph.com"
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#storage-provider-types)  Storage Provider Types

Storage providers are configured as arrays, so environment variables use indexed notation: `STORAGE_PROVIDER_{TYPE}_{INDEX}_{FIELD}`. Indexes must start from `0` and be sequential. If an index is skipped, all indexes after the gap are ignored. See [Storage Providers](https://cosmo-docs.wundergraph.com/router/storage-providers) for more details.

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#s3-storage-provider)  S3 Storage Provider

For storing operations and configs in S3-compatible storage.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| STORAGE\_PROVIDER\_S3\_{n}\_ID | id |  | The ID of the provider to reference in other configurations |  |
| STORAGE\_PROVIDER\_S3\_{n}\_ENDPOINT | endpoint |  | The endpoint of the S3 service |  |
| STORAGE\_PROVIDER\_S3\_{n}\_ACCESS\_KEY | access\_key |  | The access key for the S3 service |  |
| STORAGE\_PROVIDER\_S3\_{n}\_SECRET\_KEY | secret\_key |  | The secret key for the S3 service |  |
| STORAGE\_PROVIDER\_S3\_{n}\_BUCKET | bucket |  | The bucket where objects will be stored |  |
| STORAGE\_PROVIDER\_S3\_{n}\_REGION | region |  | The region of the S3 bucket |  |
| STORAGE\_PROVIDER\_S3\_{n}\_SECURE | secure |  | Whether to use HTTPS for S3 connections | false |

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#cdn-storage-provider)  CDN Storage Provider

For connecting to the Cosmo CDN.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| STORAGE\_PROVIDER\_CDN\_{n}\_ID | id |  | The ID of the provider to reference in other configurations |  |
| STORAGE\_PROVIDER\_CDN\_{n}\_URL | url |  | The URL of the CDN | [https://cosmo-cdn.wundergraph.com](https://cosmo-cdn.wundergraph.com/) |

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#redis-storage-provider)  Redis Storage Provider

Used for distributed caching like automatic persisted queries.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| STORAGE\_PROVIDER\_REDIS\_{n}\_ID | id |  | The ID of the provider to reference in other configurations |  |
| STORAGE\_PROVIDER\_REDIS\_{n}\_URLS | urls |  | List of Redis URLs to connect to. If cluster\_enabled is true, these are the seeds to discover the cluster |  |
| STORAGE\_PROVIDER\_REDIS\_{n}\_CLUSTER\_ENABLED | cluster\_enabled |  | Whether to use the Redis Cluster client | false |

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#file-system-storage-provider)  File System Storage Provider

This provider allows you to load files from the local file system.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| STORAGE\_PROVIDER\_FS\_{n}\_ID | id |  | The ID of the provider to reference in other configurations |  |
| STORAGE\_PROVIDER\_FS\_{n}\_PATH | path |  | The path on the file system where files should be loaded from |  |

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#persisted-operations)  Persisted Operations

The configuration for the persisted operations allows you to maintain a fixed set of GraphQL operations that can be queried against the router without exposing your entire graph to the public. This approach enhances security and performance.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-25)  Example YAML config:

config.yaml

```
version: "1"

persisted_operations:
  disabled: false
  log_unknown: false
  safelist:
    enabled: false
  cache:
    size: 100MB
  storage:
    provider_id: s3
    object_prefix: wundergraph
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#persisted-operations-configuration-options)  Persisted Operations Configuration Options

These rules apply to requests being made from the Router to all Subgraphs.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | persisted\_operations |  | The configuration for the persisted operations. |  |
| PERSISTED\_OPERATIONS\_DISABLED | persisted\_operations.disabled |  | Disable persisted operations. When set to true, the PQL manifest is also disabled. | false |
|  | persisted\_operations.cache |  | LRU cache for persisted operations. |  |
| PERSISTED\_OPERATIONS\_CACHE\_SIZE | persisted\_operations.cache.size |  | The size of the cache in SI unit. | ”100MB” |
|  | persisted\_operations.storage |  | The storage provider for persisted operation. Only one provider can be active. When no provider is specified, the router will fallback to the Cosmo CDN provider to download the persisted operations. |  |
| PERSISTED\_OPERATIONS\_STORAGE\_PROVIDER\_ID | persisted\_operations.storage.provider\_id |  | The ID of the storage provider. The ID must match the ID of the storage provider in the `storage_providers` section. |  |
| PERSISTED\_OPERATIONS\_STORAGE\_OBJECT\_PREFIX | persisted\_operations.storage.object\_prefix |  | The prefix of the object in the storage provider location. The prefix is put in front of the operation SHA256 hash. $prefix/SHA256.json |  |
| PERSISTED\_OPERATIONS\_LOG\_UNKNOWN | persisted\_operations.log\_unknown |  | Log operations (sent with the operation body) which haven’t yet been persisted. If the value is true, all operations not yet persisted are logged to the router logs. | false |
| PERSISTED\_OPERATIONS\_SAFELIST\_ENABLED | persisted\_operations.safelist.enabled |  | Only allows persisted operations (sent with operation body). If the value is true, all operations not explicitly added to the safelist are blocked. | false |
| PERSISTED\_OPERATIONS\_MANIFEST\_ENABLED | persisted\_operations.manifest.enabled |  | Enable the PQL manifest. When enabled, the router loads all persisted operations from a single manifest file and serves them from memory. Uses the `storage` config above when a provider is set, otherwise fetches from the Cosmo CDN. Only S3 and CDN storage providers are supported. | false |
| PERSISTED\_OPERATIONS\_MANIFEST\_FILE\_NAME | persisted\_operations.manifest.file\_name |  | The manifest file name. Only used when a custom storage provider is configured. The router resolves the full object path as `<object_prefix>/<file_name>`. Use a `.gz` or `.zst` extension (e.g. `manifest.json.gz`) to enable transparent decompression. Ignored in CDN mode. | manifest.json |
| PERSISTED\_OPERATIONS\_MANIFEST\_POLL\_INTERVAL | persisted\_operations.manifest.poll\_interval |  | The interval at which the router polls the Cosmo CDN for manifest updates (only when no storage provider is configured). Minimum 10s. | 10s |
| PERSISTED\_OPERATIONS\_MANIFEST\_POLL\_JITTER | persisted\_operations.manifest.poll\_jitter |  | Random jitter added to each poll interval to avoid thundering herd. Minimum 1s. | 5s |

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#automatic-persisted-queries)  Automatic Persisted Queries

The configuration for automatic persisted queries allows you to enable automated caching of select GraphQL operations that can be queried against the router, using both POST and GET requests. This approach enhances performance.It defaults to using a local cache (with the size defined in `cache.size`), but users can optionally use a Redis storage

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-26)  Example YAML config:

config.yaml

```
version: "1"

automatic_persisted_queries:
  enabled: true
  cache:
    size: 10MB # This is only relevant for an in-memory cache that we maintain
    ttl: 900 # in seconds, set both for a local and a remote KV
  storage:
    provider_id: "my_redis"
    object_prefix: cosmo_apq
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#configuration-options)  Configuration Options

These rules apply to requests being made from the Router to all Subgraphs.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | automatic\_persisted\_queries |  | The configuration for the persisted operations. |  |
|  | automatic\_persisted\_queries.enabled |  | Whether or not automatic persisted queries is enabled | true |
|  | automatic\_persisted\_queries.cache |  | LRU cache for persisted operations. |  |
|  | automatic\_persisted\_queries.cache.size |  | The size of the cache in SI unit. | ”100MB” |
|  | automatic\_persisted\_queries.cache.ttl |  | The TTL of the cache, in seconds. Set to 0 to set no TTL |  |
|  | automatic\_persisted\_queries.storage |  | The external storage provider (redis) for automatic persisted operation. Only one provider can be active. When no provider is specified, the router will fallback to using a local in-memory cache (configured in the `automatic_persisted_queries.cache` options) |  |
|  | automatic\_persisted\_queries.storage.provider\_id |  | The ID of the Redis storage provider. The ID must match the ID of the storage provider in the `storage_providers.redis` section. |  |
|  | automatic\_persisted\_queries.storage.object\_prefix |  | The prefix of the object in the storage provider location. The prefix is put in front of the operation SHA256 hash. $prefix/SHA256 |  |

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#execution-config)  Execution Config

The configuration for the execution setup contains instructions for the router to plan and execute your GraphQL operations. You can specify the storage provider from which the configuration should be fetched.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-27)  Example YAML config:

The execution config source is exclusive. Configure exactly one of `storage`, `file`, or `manifest`. `fallback_storage` is the only field that may be combined with `storage` and is used to retry from a secondary location when the primary storage provider fails.

Storage provider

Local file

Local manifest

Fallback storage

```
version: "1"
execution_config:
  storage:
    provider_id: s3
    object_path: "router.json"
```

```
version: "1"
execution_config:
  file:
    path: "./__schemas/config.json"
    watch: true
    watch_interval: "1s"
```

```
version: "1"
execution_config:
  manifest:
    path: "./__schemas/manifest"
    skip_missing_feature_flags: false
    ignored_feature_flags:
      - "experimental-checkout"
    watch: true
    watch_interval: "1s"
```

```
version: "1"
execution_config:
  storage:
    provider_id: s3
    object_path: "router.json"
  fallback_storage:
    enabled: true
    provider_id: minio
    object_path: "router.json"
```

A manifest directory contains a `mapper.json` indexing the base graph and every feature flag by version, a `latest.json` with the base graph’s execution config, and one `feature-flags/<name>.json` per feature flag. When `watch` is enabled, the router watches `mapper.json`. Whenever the file’s mtime changes, the router reloads the assembled config without downtime.When using a storage provider, the `object_path` field points to the file in your bucket that is updated after each schema deployment in your CI/CD pipeline:

```
# Publish your subgraph
wgc subgraph publish my-subgraph --schema ./schema.graphqls
# Download the latest execution config after successful composition
wgc router fetch mygraph -o router.json
# Upload the execution config to your S3 storage
aws s3 cp router.json s3://cosmo/
```

The router will check for updates every 10 seconds (default) and hot-reload accordingly without impacting current user traffic.You can configure a fallback storage for fetching the execution config in the event the router cannot reach the primary storage. You cannot use the same provider for both primary and fallback storage.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#execution-config-options)  Execution config options

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | execution\_config |  | The configuration for the execution config. |  |
|  | file |  | The configuration for the execution config file. The config file is used to load the execution config from the local file system. The file has precedence over the storage provider. |  |
| EXECUTION\_CONFIG\_FILE\_PATH | file.path |  | The path to the execution config file. The path is used to load the execution config from the local file system. |  |
| EXECUTION\_CONFIG\_FILE\_WATCH | file.watch |  | Enable the watch mode. The watch mode is used to watch the execution config file for changes. If the file changes, the router will reload the execution config without downtime. | true |
| EXECUTION\_CONFIG\_FILE\_WATCH\_INTERVAL | file.watch\_interval |  | The interval at which the file is checked for changes. | 1s |
|  | manifest |  | The configuration for loading the execution config from a local manifest directory. The directory contains `mapper.json`, `latest.json`, and one `feature-flags/<name>.json` per feature flag. Mutually exclusive with `file` and `storage`. |  |
| EXECUTION\_CONFIG\_MANIFEST\_PATH | manifest.path |  | The path to the manifest directory. |  |
| EXECUTION\_CONFIG\_MANIFEST\_SKIP\_MISSING\_FEATURE\_FLAGS | manifest.skip\_missing\_feature\_flags |  | Skip feature flags listed in `mapper.json` whose execution config file cannot be loaded, instead of aborting the load. | false |
| EXECUTION\_CONFIG\_MANIFEST\_IGNORED\_FEATURE\_FLAGS | manifest.ignored\_feature\_flags |  | Feature flag names to skip entirely when loading the manifest. Listed flags are not loaded even when referenced by `mapper.json`. |  |
| EXECUTION\_CONFIG\_MANIFEST\_WATCH | manifest.watch |  | Enable the watch mode. When enabled, the router stats `mapper.json` for changes and reloads the assembled execution config without downtime. | false |
| EXECUTION\_CONFIG\_MANIFEST\_WATCH\_INTERVAL | manifest.watch\_interval |  | The interval at which `mapper.json` is checked for changes. Only applied when `manifest.watch` is enabled. | 1s |
|  | execution\_config.storage |  | The storage provider for the execution config. Only one provider can be active. When no provider is specified, the router will fallback to the Cosmo CDN provider to download the execution config. |  |
| EXECUTION\_CONFIG\_STORAGE\_PROVIDER\_ID | execution\_config.storage.provider\_id |  | The ID of the storage provider. The ID must match the ID of the storage provider in the `storage_providers` section. |  |
| EXECUTION\_CONFIG\_STORAGE\_OBJECT\_PATH | execution\_config.storage.object\_path |  | The path to the execution config in the storage provider. The path is used to download the execution config from the S3 bucket. |  |
| EXECUTION\_CONFIG\_FALLBACK\_STORAGE\_ENABLED | execution\_config.fallback\_storage.enabled |  | Enable a fallback storage to fetch the execution config in case the above primary source fails. | false |
| EXECUTION\_CONFIG\_FALLBACK\_STORAGE\_PROVIDER\_ID | execution\_config.fallback\_storage.provider\_id |  | The ID of the storage provider. The ID must match the ID of the storage provider in the `storage_providers` section. |  |
| EXECUTION\_CONFIG\_FALLBACK\_STORAGE\_OBJECT\_PATH | execution\_config.fallback\_storage.object\_path |  | The path to the execution config in the storage provider. The path is used to download the execution config from the S3 bucket. |  |

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#split-config-poller)  Split Config Poller

The split-config polling strategy assembles the final router execution config by fetching the base graph and each feature flag config as separate files from the CDN. These rules govern its behavior when individual feature flag files are missing or should be excluded entirely. They are only applied when the router is enrolled in split-config loading; with a custom storage provider the router falls back to the regular polling strategy and these rules have no effect.The base graph is always required. Skip and ignore rules apply to feature flags only. A missing or unfetchable base graph always aborts the poll cycle, regardless of these rules.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-28)  Example YAML config:

config.yaml

```
version: "1"

split_config_poller:
  skip_missing_feature_flags: true
  ignored_feature_flags:
    - "experimental-checkout"
    - "ab-test-foo"
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#split-config-poller-options)  Split config poller options

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| SPLIT\_CONFIG\_POLLER\_SKIP\_MISSING\_FEATURE\_FLAGS | split\_config\_poller.skip\_missing\_feature\_flags |  | Keep polling alive when a feature flag listed in the mapper cannot be fetched (responds with `file not found`). When false, a single missing feature flag aborts the poll cycle. | false |
| SPLIT\_CONFIG\_POLLER\_IGNORED\_FEATURE\_FLAGS | split\_config\_poller.ignored\_feature\_flags |  | Feature flag names to skip entirely during polling. Listed flags are not fetched even when present in the mapper, and are absent from the assembled execution config. | \[\] |

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#traffic-shaping)  Traffic Shaping

Configure rules for traffic shaping like maximum request body size, timeouts, retry behavior, etc. For more info, check this section in the docs: [Traffic shaping](https://cosmo-docs.wundergraph.com/router/traffic-shaping)

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-29)  Example YAML config:

```
version: "1"

# Traffic configuration
# See "https://cosmo-docs.wundergraph.com/router/traffic-shaping" for more information
traffic_shaping:
  # Apply to all requests from clients to the router
  router:
    # Is the maximum size of the request body in MB, mib
    max_request_body_size: 5MB
    max_header_bytes: 1MiB
    decompression_enabled: true
    response_compression_min_size: 4KiB
  all: # Rules are applied to all subgraph requests.
    # Subgraphs transport options
    request_timeout: 60s
    dial_timeout: 30s
    tls_handshake_timeout: 0s
    response_header_timeout: 0s
    expect_continue_timeout: 0s
    keep_alive_idle_timeout: 90s
    keep_alive_probe_interval: 30s
    max_idle_conns: 1024
    max_conns_per_host: 100
    max_idle_conns_per_host: 20
    # Retry
    retry: # Rule is only applied to GraphQL operations of type "query"
      enabled: true
      algorithm: "backoff_jitter"
      max_attempts: 5
      interval: 3s
      max_duration: 10s
      condition: "IsRetryableStatusCode() || IsConnectionError() || IsTimeout()"
    # Circuit Breaker
    circuit_breaker:
      enabled: true
      request_threshold: 20
      error_threshold_percentage: 50
      sleep_window: 30s
      half_open_attempts: 5
      required_successful: 3
      rolling_duration: 60s
      num_buckets: 10
      execution_timeout: 60s
      max_concurrent_requests: -1

subgraphs: # allows you to create subgraph specific traffic shaping rules
    products: # Will only affect this subgraph, and override the options in "all" for that subgraph
      request_timeout: 60s
      dial_timeout: 30s
      keep_alive_idle_timeout: 0s
      keep_alive_probe_interval:
      tls_handshake_timeout: 10s
      response_header_timeout: 0s
      expect_continue_timeout: 0s
      max_idle_conns: 1024
      max_conns_per_host: 100
      max_idle_conns_per_host: 20
      # You can configure circuit breakers per subgraph, which includes the above configurations
      circuit_breaker:
        enabled: false
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#subgraph-request-rules)  Subgraph Request Rules

These rules apply to requests being made from the Router to all Subgraphs.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | retry |  | [#traffic-shaping-jitter-retry](https://cosmo-docs.wundergraph.com/router/configuration#traffic-shaping-jitter-retry) |  |
|  | circuit\_breaker |  | [#circuit-breaker](https://cosmo-docs.wundergraph.com/router/configuration#circuit-breaker) |  |
|  | request\_timeout |  |  | 60s |
|  | dial\_timeout |  |  | 30s |
|  | response\_header\_timeout |  |  | 0s |
|  | expect\_continue\_timeout |  |  | 0s |
|  | tls\_handshake\_timeout |  |  | 10s |
|  | keep\_alive\_idle\_timeout |  |  | 90s |
|  | keep\_alive\_probe\_interval |  |  | 30s |
|  | max\_idle\_conns |  |  | 1024 |
|  | max\_conns\_per\_host |  |  | 100 |
|  | max\_idle\_conns\_per\_host |  |  | 20 |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#subgraph-specific-request-rules)  Subgraph specific request rules

In addition to the general traffic shaping rules, we also allow users to set subgraph specific timeout options, overriding the default traffic rules defined in `all`(if present)

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | request\_timeout |  |  | 60s |
|  | dial\_timeout |  |  | 30s |
|  | response\_header\_timeout |  |  | 0s |
|  | expect\_continue\_timeout |  |  | 0s |
|  | keep\_alive\_idle\_timeout |  |  | 90s |
|  | keep\_alive\_probe\_interval |  |  | 30s |
|  | max\_idle\_conns |  |  | 1024 |
|  | max\_conns\_per\_host |  |  | 100 |
|  | max\_idle\_conns\_per\_host |  |  | 20 |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#circuit-breaker)  Circuit Breaker

Configure circuit breaker either for all subgraphs, or per subgraph. More information on circuit breakers can be found [here](https://cosmo-docs.wundergraph.com/router/traffic-shaping/circuit-breaker).

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | enabled |  | Enable the circuit breaker for the target (all subgraphs or a specific subgraph). | false |
|  | error\_threshold\_percentage |  | This represents the percentage of failed requests within the rolling window that will trigger the circuit to open. For example, with a 50% threshold and 100 total requests in the window, the circuit will open when 50 or more requests fail. | 50 |
|  | request\_threshold |  | Defines the minimum number of requests that must be received before the circuit breaker will evaluate error rates for potential state transitions. | 20 |
|  | sleep\_window |  | This setting determines how long the circuit will block all requests after transitioning to the open state. The sleep window serves a critical purpose: it gives the failing service time to recover without being overwhelmed by continued request attempts. | 5s |
|  | half\_open\_attempts |  | Number of test requests allowed in the half-open state. | 1 |
|  | required\_successful |  | How many successful requests are needed to close the circuit from the half-open state. This setting works in conjunction with half\_open\_attempts to determine the recovery behavior. | 1 |
|  | rolling\_duration |  | The time window for collecting error and request statistics. Only data from within this window influences circuit breaker decisions, ensuring that the circuit responds to current conditions rather than being influenced by historical problems that may have been resolved. | 10s |
|  | num\_buckets |  | Number of buckets for statistics in the rolling window (higher = finer granularity). | 10 |
|  | execution\_timeout |  | The maximum time allocated before marking a request as failed due to timeout. This timeout is specifically for circuit breaker error tracking and operates independently of any actual request timeouts. | 60s |
|  | max\_concurrent\_requests |  | This controls the maximum number of concurrent requests that the circuit breaker will process simultaneously. When set to the default value of -1, there is no limit on concurrent requests. | -1 |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#jitter-retry)  Jitter Retry

| Environment Variable | YAML | Required | Description | Default Value |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| RETRY\_ENABLED | enabled |  |  | true |  |  |  |  |
| RETRY\_ALGORITHM | algorithm |  | backoff\_jitter | backoff\_jitter |  |  |  |  |
| RETRY\_EXPRESSION | expression |  | The retry expression used to decide if a failed subgraph request should be retried. | \`IsRetryableStatusCode() |  | IsConnectionError() |  | IsTimeout()\` |
| RETRY\_MAX\_ATTEMPTS | max\_attempts |  |  |  |  |  |  |  |
| RETRY\_MAX\_DURATION | max\_duration |  |  |  |  |  |  |  |
| RETRY\_INTERVAL | interval |  |  |  |  |  |  |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#client-request-request-rules)  Client Request Request Rules

These rules apply to requests being made from clients to the Router.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | max\_request\_body\_size |  |  | 5mb |
| MAX\_HEADER\_BYTES | max\_header\_bytes |  | Minimum Router version: [0.156.0](https://github.com/wundergraph/cosmo/compare/router@0.155.0...router@0.156.0) The maximum size of the request headers. Setting this to 0 uses the default value from the http standard lib, which is 1MiB. | 1mib |
|  | decompression\_enabled |  | When enabled, the router will check incoming requests for a ‘Content-Encoding’ header and decompress the body accordingly Note: Currently only “gzip” is supported | true |
|  | response\_compression\_min\_size |  | The minimum size of the response body in bytes to enable response compression. The size is specified as a string with a number and a unit, e.g. 10KB, 1MB, 1GB | 4KiB |
| 5mb |  |  |  |  |

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#websocket)  WebSocket

Configure WebSocket handlers, protocols, and more.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#websocket-configuration)  WebSocket Configuration

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| WEBSOCKETS\_ENABLED | enabled |  |  | true |
|  | absinthe\_protocol |  | [Absinthe Protocol Configuration](https://cosmo-docs.wundergraph.com/router/configuration#absinthe-protocol-configuration) |  |
|  | forward\_upgrade\_headers |  | Forward all useful Headers from the Upgrade Request, like User-Agent or Authorization in the extensions field when subscribing on a Subgraph |  |
|  | forward\_upgrade\_query\_params |  | Forward all query parameters from the Upgrade Request in the extensions field when subscribing on a Subgraph |  |
|  | forward\_initial\_payload |  | Forward the initial payload from a client subscription in the extensions field when subscribing on a Subgraph | true |
|  | client\_info\_from\_initial\_payload |  | [WebSocket Client Info Configuration](https://cosmo-docs.wundergraph.com/router/configuration#websocket-client-info-configuration) |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#absinthe-protocol-configuration)  Absinthe Protocol Configuration

Legacy WebSocket clients that use the Absinthe protocol might not be able to send a Subprotocol Header. For such clients, you can use the Absinthe Endpoint which automatically chooses the Subprotocol for them so that no Subprotocol Header needs to be set.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| WEBSOCKETS\_ABSINTHE\_ENABLED | enabled |  |  | true |
| WEBSOCKETS\_ABSINTHE\_HANDLER\_PATH | handler\_path |  | The path to mount the Absinthe handler on | /absinthe/socket |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#websocket-authentication)  WebSocket Authentication

It’s possible that Authentication for a WebSocket connection is not possible at the HTTP layer. In such a case, you can enable Authentication “from\_initial\_payload”. This will extract a value from the “initial\_payload” field in the first WebSocket message which is responsible for negotiating the protocol between client and server.In addition, it’s possible to export the extracted value into a Request Header, which allows the Router to propagate it using [Header Propagation Rules](https://cosmo-docs.wundergraph.com/router/configuration#global-header-rules) in subsequent Subgraph Requests.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#websocket-client-info-configuration)  WebSocket Client Info Configuration

Configure how to extract client info from the initial WebSocket payload. This allows you to set client name and version information from the initial connection payload, which can then be forwarded to request headers if needed.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| WEBSOCKETS\_CLIENT\_INFO\_FROM\_INITIAL\_PAYLOAD\_ENABLED | enabled |  | Enable extracting client info from initial payload | true |
| WEBSOCKETS\_CLIENT\_INFO\_FROM\_INITIAL\_PAYLOAD\_NAME\_FIELD | name\_field |  | The field name in the initial payload to extract the client name from |  |
| WEBSOCKETS\_CLIENT\_INFO\_FROM\_INITIAL\_PAYLOAD\_VERSION\_FIELD | version\_field |  | The field name in the initial payload to extract the client version from |  |
| WEBSOCKETS\_CLIENT\_INFO\_FROM\_INITIAL\_PAYLOAD\_FORWARD\_TO\_REQUEST\_HEADERS\_ENABLED | forward\_to\_request\_headers.enabled |  | Enable forwarding extracted client info to request headers | true |
| WEBSOCKETS\_CLIENT\_INFO\_FROM\_INITIAL\_PAYLOAD\_NAME\_TARGET\_HEADER | forward\_to\_request\_headers.name\_target\_header |  | The header name to forward the client name to |  |
| WEBSOCKETS\_CLIENT\_INFO\_FROM\_INITIAL\_PAYLOAD\_VERSION\_TARGET\_HEADER | forward\_to\_request\_headers.version\_target\_header |  | The header name to forward the client version to |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-websocket-yaml-config)  Example WebSocket YAML config:

config.yaml

```
version: "1"

websocket:
  enabled: true
  absinthe_protocol:
    enabled: true
    handler_path: /absinthe/socket
  forward_initial_payload: true
  forward_upgrade_headers:
    enabled: true
    allow_list: # an empty list allows all headers
      - "Authorization" # forward only the Authorization Header
  forward_upgrade_query_params:
    enabled: true
    allow_list:
      - "Authorization"
  client_info_from_initial_payload:
    # enable extracting client info from initial payload
    enabled: true
    # the field name in the initial payload to extract the client name from
    name_field: "graphql-client-name"
    # the field name in the initial payload to extract the client version from
    version_field: "graphql-client-version"
    # enable forwarding extracted client info to request headers
    forward_to_request_headers:
      # enable forwarding extracted client info to request headers
      enabled: true
      # the header name to forward the client name to
      name_target_header: "GraphQL-Client-Name"
      # the header name to forward the client version to
      version_target_header: "GraphQL-Client-Version"
  authentication:
    # enable authentication from the initial payload
    from_initial_payload:
      enabled: false
      # which key to use one the initial payload to "extract" the Authorization value
      key: "authorization"
      export_token:
        export_token: false
        # to enable Subgraph authentication, we can export the value into a Header
        header_key: "Authorization"
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#authentication)  Authentication

Configure different authentication providers.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#new-authentication-config-router-version-%E2%89%A5-0-169-0)  New Authentication Config (Router Version ≥ 0.169.0)

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#jwks)  JWKS

The following configuration has two flavours

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#jwks-url-endpoint)  JWKS URL endpoint

This is useful when you want to connect to a JWKS endpoint

| YAML | Required | Description | Default Value |
| --- | --- | --- | --- |
| url |  | The URL of the JWKs. The JWKs are used to verify the JWT (JSON Web Token). The URL is specified as a string with the format ‘scheme://host:port’. |  |
| refresh\_interval |  | The interval at which the JWKs are refreshed. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’. | 1m |
| allowed\_use |  | The allowed value of the use parameter for the JWKs. If not specified, only keys with use set to ‘sig’ will be used. If your server provides no use, you can add an empty value to allow those keys. | \[“sig”\] |
| algorithms |  | The allowed algorithms for the keys that are retrieved from the JWKs. An empty list means that all algorithms are allowed. The following algorithms are supported “RS256”, “RS384”, “RS512”, “ES256”, “ES384”, “ES512”, “PS256”, “PS384”, “PS512”, “EdDSA” | \[\] (all allowed) |
| refresh\_unknown\_kid.enabled |  | Enable automatic JWKS refresh when encountering a valid token with an unknown KID (Key ID). When enabled, the router will fetch updated keys to find the matching KID. | false |
| refresh\_unknown\_kid.max\_wait |  | Maximum time a refresh is allowed to wait. If the computed wait would exceed this value, the request fails immediately with 401 Unauthorized instead of waiting. | 2m |
| refresh\_unknown\_kid.interval |  | Time between replenishing burst tokens. With burst=1, each subsequent request within the interval must wait for (interval × attempt number). | 30s |
| refresh\_unknown\_kid.burst |  | Maximum number of refreshes allowed without waiting. Prevents overloading the JWKS endpoint; beyond this, requests wait until the interval elapses or fail due to max\_wait. | 2 |

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#secret)  Secret

This is useful when you have a symmetric key that you cannot expose through a JWKS endpoint, you can use the secret based configuration

| YAML | Required | Description | Default Value |
| --- | --- | --- | --- |
| secret |  | The secret value, which will be used to construct the “k” parameter of the JWKS |  |
| header\_key\_id |  | The key id, this is required as the router use JWK Sets and is used to construct the “kid” attribute which helps identify the correct JWK |  |
| symmetric\_algorithm |  | Specify which symmetric algorithm is used for signing, supported algorithms are “HS256”, “HS384”, “HS512” |  |

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#audience-validation)  Audience Validation

In addition to the above JWKS configuration flavours, you can define a list of audiences of which one is required (if specified) with either options.

| YAML | Required | Description | Default Value |
| --- | --- | --- | --- |
| audiences |  | The allowed list of audiences, of which at least one audience is required in the token | \[\] |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#jwt)  JWT

| YAML | Required | Description | Default Value |
| --- | --- | --- | --- |
| scope\_claim |  | The JWT claim used to read scopes for authorization. Use this when your identity provider stores scopes in a claim other than `scope`. Only top level claims are supported. | scope |
| header\_name |  | The name of the header. The header is used to extract the token from the request. The default value is ‘Authorization’. | Authorization |
| header\_value\_prefix |  | The prefix of the header value. The prefix is used to extract the token from the header value. The default value is ‘Bearer’. | Bearer |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#header-sources)  Header Sources

| YAML | Required | Description | Default Value |
| --- | --- | --- | --- |
| type |  | The type of the source. The only currently supported type is ‘header’. | header |
| name |  | The name of the header. The header is used to extract the token from the request. The default value is ‘Authorization’. | Authorization |
| value\_prefixes |  | The prefixes of the header value. The prefixes are used to extract the token from the header value. The default value is ‘Bearer’. | Bearer |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-v2)  Example YAML config V2:

```
authentication:
  jwt:
    jwks:
      - url: "https://example.com/.well-known/jwks.json"
        refresh_interval: 1m
        # Leaving algorithms empty will allow all supported algorithms from the config docs
        refresh_unknown_kid:
          enabled: true
          max_wait: 2m
          interval: 30s
          burst: 2
      - url: "https://example2.com/.well-known/jwks.json"
        refresh_interval: 2m
        # optional list of allowed algorithms per JWKS
        algorithms: ["RS256", "EdDSA", "HS512"]
        refresh_unknown_kid:
          enabled: false # These are defaults
          max_wait: 2m
          interval: 30s
          burst: 2
    header_name: Authorization # This is the default value
    scope_claim: scope # This is the default value
    header_value_prefix: Bearer # This is the default value
    header_sources:
      - type: header
        name: X-Auth-Token
        value_prefixes: [Token, MyToken]
      - type: header
        name: X-Authorization
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#bypass-introspection-authentication)  Bypass Introspection Authentication

This is useful when you want to bypass authentication for introspection queries,
for example let certain tools introspect the schema without requiring authentication token.

This feature is meant to be used in secure, internal environments. It is not recommended for use in a production environment.
By default, introspection queries are not excluded from authentication.
Also consider setting `introspection.secret` for a static secret dedicated to introspection queries.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | ignore\_introspection |  | Bypass introspection authentication | false |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#old-authentication-config-router-version-%3C-0-xxx-x)  Old Authentication Config (Router Version < 0.XXX.X)

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#provider)  Provider

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | name |  | Name of the provider | My Auth Provider |
|  | jwks |  | JWKS Provider |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#jwk-provider)  JWK Provider

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | url |  |  |  |
|  | header\_names |  |  |  |
|  | header\_value\_prefixes |  |  |  |
|  | refresh\_interval |  |  | 1m |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-30)  Example YAML config:

config.yaml

```
version: "1"

# Authentication and Authorization
# See https://cosmo-docs.wundergraph.com/router/authentication-and-authorization for more information
authentication:
  providers:
    - name: My Auth Provider # Optional, used for error messages and diagnostics
      jwks: # JWKS provider configuration
        url: https://example.com/.well-known/jwks.json # URL to load the JWKS from
        header_name: Authorization # Optional
        header_value_prefix: Bearer # Optional
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#authorization)  Authorization

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| REQUIRE\_AUTHENTICATION | require\_authentication |  | Set to true to disallow unauthenticated requests | false |
| REJECT\_OPERATION\_IF\_UNAUTHORIZED | reject\_operation\_if\_unauthorized |  | If enabled, the Router will return 401 with no response data when the evaluation of field-based permissions ( [@authenticated](https://cosmo-docs.wundergraph.com/federation/directives/authenticated) or [@requiresScopes](https://cosmo-docs.wundergraph.com/federation/directives/requiresscopes) fails) | false |
| ENABLE\_PRE\_FETCH\_FIELD\_AUTHORIZATION | enable\_pre\_fetch\_field\_authorization |  | If enabled, fields protected by [@authenticated](https://cosmo-docs.wundergraph.com/federation/directives/authenticated) or [@requiresScopes](https://cosmo-docs.wundergraph.com/federation/directives/requiresscopes) are authorized in a single batch before any subgraph fetch runs, instead of filtering them from the response after the fetch. This avoids fetching data the client is not authorized to see. | false |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-31)  Example YAML config:

config.yaml

```
version: "1"

authorization:
  require_authentication: false
  reject_operation_if_unauthorized: false
  enable_pre_fetch_field_authorization: false
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#cdn)  CDN

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| CDN\_URL | url |  | The URL of the CDN where the Router will fetch its Config. Not required when a static execution config is provided. | [https://cosmo-cdn.wundergraph.com](https://cosmo-cdn.wundergraph.com/) |
| CDN\_CACHE\_SIZE | cache\_size |  | Cosmo Router caches responses from the CDN in memory, this defines the cache size. | 100MB |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-32)  Example YAML config:

config.yaml

```
version: "1"

cdn:
  url: https://cosmo-cdn.wundergraph.com
  cache_size: 100MB
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#events)  Events

The Events section lets you define Event Sources for [Cosmo Streams / EDFS](https://cosmo-docs.wundergraph.com/router/cosmo-streams).We support NATS, Kafka and Redis as event bus provider.

config.yaml

```
version: "1"

events:
  providers:
    nats:
      - id: default
        url: "nats://localhost:4222"
        authentication:
          token: "token" # or
          user_info:
            username: "username"
            password: "password"
        tls:
          ca_file: /path/to/ca.crt
          cert_file: /path/to/client.crt
          key_file: /path/to/client.key
    kafka:
      - id: my-kafka
        tls:
          enabled: true
        authentication:
          sasl_plain:
            password: "password"
            username: "username"
        brokers:
          - "localhost:9092"
    redis:
      - id: my-redis
        urls:
          - "localhost:9092"
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#provider-2)  Provider

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | providers |  | one of: nats, kafka, redis |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#nats-provider)  NATS Provider

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | id |  | The ID of the provider. This have to match with the ID specified in the subgraph schema. |  |
|  | url |  | NATS Connection string |  |
|  | authentication |  | Authentication configuration for the NATS provider. |  |
|  | authentication.token |  | Token based authentication. |  |
|  | authentication.user\_info |  | User-Info based authentication. |  |
|  | authentication.user\_info.username |  | Username. |  |
|  | authentication.user\_info.password |  | Password. |  |
|  | tls |  | TLS configuration for the NATS provider. |  |
|  | tls.insecure\_skip\_ca\_verification |  | Skip server certificate verification. Not recommended for production. | false |
|  | tls.ca\_file |  | Path to a custom CA certificate file (PEM) used to verify the server certificate. Defaults to the host’s system trust store. |  |
|  | tls.cert\_file |  | Path to the client certificate file (PEM) for mTLS. Must be set together with `key_file`. |  |
|  | tls.key\_file |  | Path to the client private key file (PEM) for mTLS. Must be set together with `cert_file`. |  |

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#tls-2)  TLS

The NATS provider supports four TLS modes:

| Mode | Config |
| --- | --- |
| No TLS | Omit the `tls` block |
| TLS with skip verify | `insecure_skip_ca_verification: true` |
| TLS with custom CA | `ca_file: /path/to/ca.crt` |
| Mutual TLS (mTLS) | `cert_file` \+ `key_file` (plus optional `ca_file`) |

Skip verify (dev/self-signed)

Custom CA (1-way TLS)

Mutual TLS (mTLS)

```
events:
  providers:
    nats:
      - id: my-nats
        url: "nats://localhost:4222"
        tls:
          insecure_skip_ca_verification: true
```

```
events:
  providers:
    nats:
      - id: my-nats
        url: "nats://localhost:4222"
        tls:
          ca_file: /path/to/ca.crt
```

```
events:
  providers:
    nats:
      - id: my-nats
        url: "nats://localhost:4222"
        tls:
          ca_file: /path/to/ca.crt
          cert_file: /path/to/client.crt
          key_file: /path/to/client.key
```

`insecure_skip_ca_verification: true` disables server certificate verification. Do not use in production.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#kafka-provider)  Kafka Provider

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | id |  | The ID of the provider. This have to match with the ID specified in the subgraph schema. | \[\] |
|  | brokers |  | A list of broker URLs. |  |
|  | authentication |  | Authentication settings |  |
|  | authentication.sasl\_plain |  | SASL/Plain Authentication method |  |
|  | authentication.sasl\_plain.username |  | SASL/Plain Username |  |
|  | authentication.sasl\_plain.password |  | SASL/Plain Password |  |
|  | authentication.sasl\_scram |  | SASL/SCRAM Authentication method |  |
|  | authentication.sasl\_scram.username |  | SASL/SCRAM Username |  |
|  | authentication.sasl\_scram.password |  | SASL/SCRAM Password |  |
|  | authentication.sasl\_scram.mechanism |  | SASL/SCRAM Mechanism, could be `SCRAM-SHA-256` of `SCRAM-SHA-512` |  |
|  | tls |  | TLS configuration for the Kafka provider. If enabled, it uses SystemCertPool for RootCAs by default. |  |
|  | tls.enabled |  | Enable the TLS. |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#redis-provider)  Redis Provider

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | id |  | The ID of the provider. This have to match with the ID specified in the subgraph schema. | \[\] |
|  | urls |  | A list of redis instances URLS, e.g: `redis://localhost:6379/2` |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#cosmo-streams-handlers)  Cosmo Streams handlers

Configuration for Cosmo Streams handlers. Learn more about [Custom Modules for Cosmo Streams](https://cosmo-docs.wundergraph.com/router/cosmo-streams/custom-modules).

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | handlers.on\_receive\_events.handler\_timeout |  | The maximum time to wait for all OnReceiveEvents handlers to complete per event-batch. | 5s |
|  | handlers.on\_receive\_events.max\_concurrent\_handlers |  | The maximum number of concurrent OnReceiveEvents handlers per trigger. | 100 |

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#router-engine-configuration)  Router Engine Configuration

Configure the GraphQL Execution Engine of the Router.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| ENGINE\_ENABLE\_SINGLE\_FLIGHT | enable\_single\_flight |  | Deduplicate exactly the same in-flight origin request | true |
| ENGINE\_ENABLE\_REQUEST\_TRACING | enable\_request\_tracing |  | Enable [Advanced Request Tracing (ART)](https://cosmo-docs.wundergraph.com/router/advanced-request-tracing-art) This config is not correlated to OTEL tracing. | true |
| ENGINE\_ENABLE\_EXECUTION\_PLAN\_CACHE\_RESPONSE\_HEADER | enable\_execution\_plan\_cache\_response\_header |  | **Deprecated**, use [“enable\_cache\_response\_headers”](https://cosmo-docs.wundergraph.com/router/configuration#debug-configuration) instead. When enabled, the Router sets the response Header “X-WG-Execution-Plan-Cache” to “HIT” or “MISS” | false |
| ENGINE\_MAX\_CONCURRENT\_RESOLVERS | max\_concurrent\_resolvers |  | Use this to limit the concurrency in the GraphQL Engine. A high number will lead to more memory usage. A number too low will slow down your Router. | 32 |
| ENGINE\_ENABLE\_NET\_POLL | enable\_net\_poll |  | Enables the more efficient poll implementation for the server-side WebSocket handler of the router. This is only available on Linux and MacOS. On Windows or when the host system is limited, the default synchronous implementation is used. Has no effect on the router’s upstream connections to subgraphs. | true |
| ENGINE\_WEBSOCKET\_SERVER\_READ\_TIMEOUT | websocket\_server\_read\_timeout |  | Read timeout on the server-side WebSocket handler (router accepting clients). Specified as a Go duration string, e.g. `10ms`, `1s`, `1m`. | 5s |
| ENGINE\_WEBSOCKET\_SERVER\_WRITE\_TIMEOUT | websocket\_server\_write\_timeout |  | Write timeout on the server-side WebSocket handler (router accepting clients). | 10s |
| ENGINE\_WEBSOCKET\_SERVER\_POLL\_TIMEOUT | websocket\_server\_poll\_timeout |  | The timeout for the poll loop of the server-side WebSocket handler. The period is specified as a string with a number and a unit. | 1s |
| ENGINE\_WEBSOCKET\_SERVER\_CONN\_BUFFER\_SIZE | websocket\_server\_conn\_buffer\_size |  | The buffer size for the poll buffer of the server-side WebSocket handler. The buffer size determines how many connections can be handled in one loop. | 128 |
| ENGINE\_WEBSOCKET\_CLIENT\_WRITE\_TIMEOUT | websocket\_client\_write\_timeout |  | The timeout for the websocket write of the WebSocket client implementation. | 10s |
| ENGINE\_WEBSOCKET\_CLIENT\_PING\_INTERVAL | websocket\_client\_ping\_interval |  | The Websocket client ping interval to the subgraph. Defines how often the router will ping the subgraph to signal that the connection is still alive. Timeout needs to be coordinated with the subgraph. The timeout is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’. | 15s |
| ENGINE\_WEBSOCKET\_CLIENT\_PING\_TIMEOUT | websocket\_client\_ping\_timeout |  | The Websocket client ping timeout to the subgraph. Defines how long the router will wait for a ping response from the subgraph. The timeout is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’. | 30s |
| ENGINE\_WEBSOCKET\_CLIENT\_ACK\_TIMEOUT | websocket\_client\_ack\_timeout |  | How long the router waits for a `connection_ack` from a subgraph after sending `connection_init`. Minimum `1s`. | 30s |
| ENGINE\_WEBSOCKET\_CLIENT\_READ\_LIMIT | websocket\_client\_read\_limit |  | Maximum size of an incoming WebSocket message from a subgraph. Specified as a byte string, e.g. `512KB`, `1MB`. Minimum `1KB`. | 1MB |
| ENGINE\_EXECUTION\_PLAN\_CACHE\_SIZE | execution\_plan\_cache\_size |  | Define how many GraphQL Operations should be stored in the execution plan cache. A low number will lead to more frequent cache misses, which will lead to increased latency. | 1024 |
| ENGINE\_SLOW\_PLAN\_CACHE\_SIZE | slow\_plan\_cache\_size |  | The maximum number of entries in the slow plan cache. This cache protects slow-to-plan queries from being evicted by the main plan cache’s LFU policy. Only used when `in_memory_fallback` is enabled. See [Slow Plan Cache](https://cosmo-docs.wundergraph.com/concepts/cache-warmer#slow-plan-cache). | 300 |
| ENGINE\_SLOW\_PLAN\_CACHE\_THRESHOLD | slow\_plan\_cache\_threshold |  | The minimum planning duration for a query to be promoted into the slow plan cache. Queries that take longer than this threshold to plan are considered expensive and protected from eviction. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 5s. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’. | 100ms |
| ENGINE\_MINIFY\_SUBGRAPH\_OPERATIONS | minify\_subgraph\_operations |  | Minify the subgraph operations. If the value is true, GraphQL Operations get minified after planning. This reduces the amount of GraphQL AST nodes the Subgraph has to parse, which ultimately saves CPU time and memory, resulting in faster response times. | false |
| ENGINE\_ENABLE\_PERSISTED\_OPERATIONS\_CACHE | enable\_persisted\_operations\_cache |  | Enable the persisted operations cache. The persisted operations cache is used to cache normalized persisted operations to improve performance. | true |
| ENGINE\_ENABLE\_NORMALIZATION\_CACHE | enable\_normalization\_cache |  | Enable the normalization cache. The normalization cache is used to cache normalized operations to improve performance. | true |
| ENGINE\_NORMALIZATION\_CACHE\_SIZE | normalization\_cache\_size |  | The size of the normalization cache. | 1024 |
| ENGINE\_PARSEKIT\_POOL\_SIZE | parsekit\_pool\_size |  | The size of the ParseKit pool. The ParseKit pool provides re-usable Resources for parsing, normalizing, validating and planning GraphQL Operations. Setting the pool size to a value much higher than the number of CPU Threads available will not improve performance, but only increase memory usage. | 8 |
| ENGINE\_RESOLVER\_MAX\_RECYCLABLE\_PARSER\_SIZE | resolver\_max\_recyclable\_parser\_size |  | Limits the size of the Parser that can be recycled back into the Pool. If set to 0, no limit is applied. This helps keep the Heap size more maintainable if you regularly perform large queries. | 32768 |
| ENGINE\_ENABLE\_VALIDATION\_CACHE | enable\_validation\_cache |  | Enable the validation cache. The validation cache is used to cache results of validating GraphQL Operations. | true |
| ENGINE\_VALIDATION\_CACHE\_SIZE | validation\_cache\_size |  | The size of the validation cache. | 1024 |
| ENGINE\_DISABLE\_EXPOSING\_VARIABLES\_CONTENT\_ON\_VALIDATION\_ERROR | disable\_exposing\_variables\_content\_on\_validation\_error |  | Disables exposing the variables content in the error response. This is useful to avoid leaking sensitive information in the error response. | false |
| ENGINE\_ENABLE\_SUBGRAPH\_FETCH\_OPERATION\_NAME | enable\_subgraph\_fetch\_operation\_name |  | Enable appending the operation name to subgraph fetches. This will ensure that the operation name will be included in the corresponding subgraph requests using the following format: `$OperationName__$SubgraphName__$FetchID`. | false |
| ENGINE\_ENABLE\_REQUIRE\_FETCH\_REASONS | enable\_require\_fetch\_reasons |  | Enable the openfed\_\_requireFetchReasons directive, and forces the adding of the “fetch\_reasons” extension to upstream subgraph requests. This extension explains why each field was requested. | false |
| ENGINE\_VALIDATE\_REQUIRED\_EXTERNAL\_FIELDS | validate\_required\_external\_fields |  | Validate nullable external “@requires” dependencies. When a subgraph entity fetch returns a null value with an error for a field set specified in the “@requires” directive, any following fetch that depends on it should not receive such an entity. | false |
| ENGINE\_SUBSCRIPTION\_FETCH\_TIMEOUT | subscription\_fetch\_timeout |  | The maximum time a subscription fetch can take before it is considered timed out. | 30s |
| ENGINE\_ENABLE\_DEFER | enable\_defer |  | Enables support for the `@defer` directive, allowing clients to defer parts of a query so that the initial response is returned faster and deferred fields are streamed incrementally. | false |
| ENGINE\_RELAX\_SUBGRAPH\_OPERATION\_FIELD\_SELECTION\_MERGING\_NULLABILITY | relax\_subgraph\_operation\_field\_selection\_merging\_nullability |  | Relaxes nullability validation for [field selection merging](https://cosmo-docs.wundergraph.com/router/relaxed-field-selection-merging-nullability) across union member types. | false |
| ENGINE\_ALLOW\_STRING\_LITERALS\_FOR\_ENUMS | allow\_string\_literals\_for\_enums |  | Accepts a [string literal where an enum value is expected](https://cosmo-docs.wundergraph.com/router/string-literals-for-enums) if the string content matches one of the enum’s values. This is a deviation from the GraphQL specification. | false |

**Subject to change.**`enable_net_poll`, `websocket_server_poll_timeout`, and `websocket_server_conn_buffer_size` may be removed or changed in a future release without a standard deprecation cycle. Avoid depending on them.

If you’re upgrading from a previous release and set `websocket_client_read_timeout`, `websocket_client_poll_timeout`, `websocket_client_conn_buffer_size`, `websocket_client_frame_timeout`, or `websocket_client_write_timeout`, see the [subscriptions overhaul migration guide](https://cosmo-docs.wundergraph.com/router/subscriptions-migration). Several of these were removed and one (`websocket_client_write_timeout`) kept its name but changed scope.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-33)  Example YAML config:

config.yaml

```
version: "1"

engine:
  enable_single_flight: true
  enable_request_tracing: true
  max_concurrent_resolvers: 32
  enable_websocket_epoll_kqueue: true
  epoll_kqueue_poll_timeout: "1s"
  epoll_kqueue_conn_buffer_size: 128
  # Server-side WebSocket handler (router accepting clients)
  websocket_server_read_timeout: "5s"
  websocket_server_write_timeout: "10s"
  websocket_server_poll_timeout: "1s"
  websocket_server_conn_buffer_size: 128
  # Upstream subscription client (router connecting to subgraphs)
  websocket_client_write_timeout: "10s"
  websocket_client_ping_interval: "15s"
  websocket_client_ping_timeout: "30s"
  websocket_client_ack_timeout: "30s"
  websocket_client_read_limit: "1MB"
  execution_plan_cache_size: 10000
  slow_plan_cache_size: 300
  slow_plan_cache_threshold: 100ms
  minify_subgraph_operations: true
  enable_persisted_operations_cache: true
  enable_normalization_cache: true
  normalization_cache_size: 1024
  parsekit_pool_size: 8
  enable_validation_cache: true
  validation_cache_size: 1024
  disable_exposing_variables_content_on_validation_error: false
  enable_subgraph_fetch_operation_name: true
  subscription_fetch_timeout: 30s
  relax_subgraph_operation_field_selection_merging_nullability: false
  allow_string_literals_for_enums: false
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#debug-configuration)  Debug Configuration

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| ENGINE\_DEBUG\_PRINT\_OPERATION\_TRANSFORMATIONS | print\_operation\_transformations |  | Print the operation transformations. | false |
| ENGINE\_DEBUG\_PRINT\_OPERATION\_ENABLE\_AST\_REFS | print\_operation\_enable\_ast\_refs |  | Print the operation enable AST refs. | false |
| ENGINE\_DEBUG\_PRINT\_PLANNING\_PATHS | print\_planning\_paths |  | Print the planning paths. | false |
| ENGINE\_DEBUG\_PRINT\_QUERY\_PLANS | print\_query\_plans |  | Print the query plans. | false |
| ENGINE\_DEBUG\_PRINT\_NODE\_SUGGESTIONS | print\_node\_suggestions |  | Print the node suggestions. | false |
| ENGINE\_DEBUG\_CONFIGURATION\_VISITOR | configuration\_visitor |  | Print the configuration visitor. | false |
| ENGINE\_DEBUG\_PLANNING\_VISITOR | planning\_visitor |  | Print the planning visitor. | false |
| ENGINE\_DEBUG\_DATASOURCE\_VISITOR | datasource\_visitor |  | Print the datasource visitor. | false |
| ENGINE\_DEBUG\_REPORT\_WEBSOCKET\_CONNECTIONS | report\_websocket\_connections |  | Print the websocket connections. | false |
| ENGINE\_DEBUG\_REPORT\_MEMORY\_USAGE | report\_memory\_usage |  | Print the memory usage. | false |
| ENGINE\_DEBUG\_ENABLE\_RESOLVER\_DEBUGGING | enable\_resolver\_debugging |  | Enable verbose debug logging for the Resolver. | false |
| ENGINE\_DEBUG\_ENABLE\_CACHE\_RESPONSE\_HEADERS | enable\_cache\_response\_headers |  | Enable hit/miss response headers for the normalization caches (“X-WG-Normalization-Cache”, “X-WG-Variables-Normalization-Cache”, “X-WG-Variables-Remapping-Cache”), the persisted operations cache (“X-WG-Persisted-Operation-Cache”), and the execution plan cache (“X-WG-Execution-Plan-Cache”). | false |
| ENGINE\_DEBUG\_ENABLE\_PERSISTED\_OPERATIONS\_CACHE\_RESPONSE\_HEADER | enable\_persisted\_operations\_cache\_response\_header |  | **Deprecated**, use “enable\_cache\_response\_headers” instead. Enable the persisted operations cache response header. The persisted operations cache response header is used to cache the persisted operations in the client. | false |
| ENGINE\_DEBUG\_ENABLE\_NORMALIZATION\_CACHE\_RESPONSE\_HEADER | enable\_normalization\_cache\_response\_header |  | **Deprecated**, use “enable\_cache\_response\_headers” instead. Enable the normalization cache response header. The normalization cache response header is used to cache the normalized operations in the client. | false |
| ENGINE\_DEBUG\_ALWAYS\_INCLUDE\_QUERY\_PLAN | always\_include\_query\_plan |  | Always include the query plan in the response. | false |
| ENGINE\_DEBUG\_ALWAYS\_SKIP\_LOADER | always\_skip\_loader |  | Always skip the loader. This will return no data but only render response extensions, e.g. to expose the query plan. | false |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-34)  Example YAML config:

config.yaml

```
version: "1"

engine:
  debug:
    print_operation_transformations: false
    print_operation_enable_ast_refs: false
    print_planning_paths: false
    print_query_plans: false
    print_node_suggestions: false
    configuration_visitor: false
    planning_visitor: false
    datasource_visitor: false
    report_websocket_connections: false
    report_memory_usage: false
    enable_resolver_debugging: false
    enable_persisted_operations_cache_response_header: false
    enable_normalization_cache_response_header: false
    always_include_query_plan: false
    always_skip_loader: false
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#validate-inline-arguments)  Validate Inline Arguments

The configuration for [Validate Inline Arguments](https://cosmo-docs.wundergraph.com/router/security/validate-inline-arguments). Detects, and
optionally rejects, operations that pass argument values inline instead of through variables.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| ENGINE\_VALIDATE\_INLINE\_ARGUMENTS\_MODE | mode |  | `off` disables the feature; `permissive` detects and records inline arguments while still executing; `strict` rejects operations that use inline argument values. | off |
| ENGINE\_VALIDATE\_INLINE\_ARGUMENTS\_ENFORCE\_HTTP\_STATUS\_CODE | enforce\_http\_status\_code |  | HTTP status code returned when an operation is rejected in enforcing mode. | 400 |
| ENGINE\_VALIDATE\_INLINE\_ARGUMENTS\_ERROR\_CODE | error\_code |  | The `extensions.code` set on the rejection error. | INLINE\_ARGUMENT\_VALUES\_NOT\_ALLOWED |
| ENGINE\_VALIDATE\_INLINE\_ARGUMENTS\_ERROR\_MESSAGE | error\_message |  | The error message returned to the client on rejection. | Inline argument values are not allowed. Use variables instead. |
| ENGINE\_VALIDATE\_INLINE\_ARGUMENTS\_INCLUDE\_PERSISTED\_OPERATIONS | include\_persisted\_operations |  | When true, the policy also applies to persisted operations. Persisted operations are exempt by default. | false |
| ENGINE\_VALIDATE\_INLINE\_ARGUMENTS\_RETURN\_IN\_RESPONSE\_EXTENSIONS | return\_in\_response\_extensions |  | When true, detected inline arguments are returned to the client under `extensions.inlineArguments`. Applies only in non-enforcing mode. | false |

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-35)  Example YAML config:

config.yaml

```
version: "1"

engine:
  validate_inline_arguments:
    mode: permissive
    enforce_http_status_code: 400
    error_code: INLINE_ARGUMENT_VALUES_NOT_ALLOWED
    error_message: "Inline argument values are not allowed. Use variables instead."
    include_persisted_operations: false
    return_in_response_extensions: false
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#rate-limiting)  Rate Limiting

Configures a rate limiter on the outgoing subgraphs requests. When enabled, a rate of 10 req/s with a burst of 10 requests is configured.

The rate limiter requires Redis version 3.2 or newer since it relies on
[replicate\_commands](https://redis.io/commands/eval#replicating-commands-instead-of-scripts)
feature. ElastiCache for Redis only works in non-clustered mode. You can
enable a failover instance to achieve high availability.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#key-suffix-expression)  Key Suffix Expression

As you can see in the config table below, you can define an expression to generate the a rate limiting key suffix. The evaluation of the expression must return a string, which will be appended to the key prefix.Using a key suffix expression, you’re able to dynamically choose a rate limiting key, e.g. based on the user authentication, a header, or a combination. Here’s an example expression that uses the `sub` claim if available, and a Header as the fallback.

```
request.auth.claims.sub ?? request.header.Get('X-Forwarded-For')
```

For mor information on how to use the expression language, please refer to the [Template Expressions](https://cosmo-docs.wundergraph.com/router/configuration/template-expressions) section.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#general-rate-limiting-configuration)  General Rate Limiting Configuration

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| RATE\_LIMIT\_ENABLED | enabled |  | Enable / Disable rate limiting globally | false |
| RATE\_LIMIT\_STRATEGY | strategy |  | The rate limit strategy to use | simple |
|  | simple\_strategy |  | \[ |  |\
| Rate Limiting Simple Strategy\](/router/configuration#rate-limiting-simple-strategy) | simple |  |  |  |
|  | storage |  | [Rate Limiting Redis Storage](https://cosmo-docs.wundergraph.com/router/configuration#rate-limiting-redis-storage) |  |
| RATE\_LIMIT\_KEY\_SUFFIX\_EXPRESSION | key\_suffix\_expression |  | The expression to define a key suffix for the rate limit, e.g. by using request headers, claims, or a combination of both with a fallback strategy. The expression is specified as a string and needs to evaluate to a string. Please see [https://expr-lang.org/](https://expr-lang.org/) for more information. |  |
|  | error\_extension\_code |  |  |  |
| [Rate Limit Error Extension Code](https://cosmo-docs.wundergraph.com/router/configuration#rate-limit-error-extension-code) |  |  |  |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#rate-limiting-redis-storage)  Rate Limiting Redis Storage

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| RATE\_LIMIT\_REDIS\_URLS | urls |  | List of the connection URL(s). | \[redis://localhost:6379\] |
| RATE\_LIMIT\_REDIS\_CLUSTER\_ENABLED | cluster\_enabled |  | If the Redis instance is a Redis cluster | false |
| RATE\_LIMIT\_REDIS\_KEY\_PREFIX | key\_prefix |  | This prefix is used to namespace the ratelimit keys | cosmo\_rate\_limit |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#rate-limiting-simple-strategy)  Rate Limiting Simple Strategy

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| RATE\_LIMIT\_SIMPLE\_RATE | rate |  | Allowed request rate (number) | 10 |
| RATE\_LIMIT\_SIMPLE\_BURST | burst |  | Allowed burst rate (number) - max rate per one request | 10 |
| RATE\_LIMIT\_SIMPLE\_PERIOD | period |  | The rate limiting period, e.g. ”10s”, “1m”, etc… | 1s |
| RATE\_LIMIT\_SIMPLE\_REJECT\_EXCEEDING\_REQUESTS | reject\_exceeding\_requests |  | Reject the complete request if a sub-request exceeds the rate limit. If set to false, partial responses are possible. | false |
| RATE\_LIMIT\_SIMPLE\_HIDE\_STATS\_FROM\_RESPONSE\_EXTENSION | hide\_stats\_from\_response\_extension |  | Hide the rate limit stats from the response extension. If the value is true, the rate limit stats are not included in the response extension. | false |
|  | overrides |  | List of per-key rate limit overrides. The first matching override wins; unmatched keys use the global defaults. See [example below](https://cosmo-docs.wundergraph.com/router/configuration#rate-limiting-example-yaml-configuration). |  |
|  | overrides.matching |  | Go regex pattern matched against the suffix portion of the rate-limit key (the result of `key_suffix_expression`), not the full prefixed Redis key. |  |
|  | overrides.rate |  | Allowed request rate for matching keys. |  |
|  | overrides.burst |  | Allowed burst rate for matching keys. |  |
|  | overrides.period |  | Rate limiting period for matching keys, e.g. ”10s”, “1m”. |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#rate-limit-error-extension-code)  Rate Limit Error Extension Code

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| RATE\_LIMIT\_ERROR\_EXTENSION\_CODE\_ENABLED | enabled |  | If enabled, a code will be added to the extensions.code field of error objects related to rate limiting. This allows clients to easily identify if an error happened due to rate limiting. | true |
| RATE\_LIMIT\_ERROR\_EXTENSION\_CODE | code |  | The code to add to the extensions.code field of error objects related to rate limiting. | RATE\_LIMIT\_EXCEEDED |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#rate-limiting-example-yaml-configuration)  Rate Limiting Example YAML configuration

config.yaml

```
rate_limit:
    enabled: true
    strategy: "simple"
    simple_strategy:
        rate: 10
        burst: 10
        period: 1s
        reject_exceeding_requests: false
        reject_status_code: 200
        hide_stats_from_response_extension: false
        overrides:
            - matching: "^premium-.*"
              rate: 100
              burst: 200
              period: 1s
    storage:
        cluster_enabled: false
        urls:
         - "redis://localhost:6379"
        key_prefix: "cosmo_rate_limit"
    debug: false
    key_suffix_expression: "request.header.Get('X-Api-Key')"
    error_extension_code:
        enabled: true
        code: "RATE_LIMIT_EXCEEDED"
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#subgraph-data-propagation)  Subgraph Data Propagation

Controls what subgraphs can propagate back to the client. Errors and the response `extensions` object are governed by separate but related policies.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#subgraph-error-propagation)  Subgraph Error Propagation

The configuration for the subgraph error propagation. Errors can be exposed to the client in a “wrapped” form to hide Subgraph internals, or it’s possible to “pass-through” Subgraph errors directly to the client.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| SUBGRAPH\_ERROR\_PROPAGATION\_ENABLED | enabled |  | Enable error propagation. If the value is true (default: false), Subgraph errors will be propagated to the client. | false |
| SUBGRAPH\_ERROR\_PROPAGATION\_MODE | mode |  | The mode of error propagation. The supported modes are ‘wrapped’ (default) and ‘pass-through’. The ‘wrapped’ mode wraps the error in a custom error object to hide internals. The ‘pass-through’ mode returns the error as is from the Subgraph. | wrapped |
| SUBGRAPH\_ERROR\_PROPAGATION\_REWRITE\_PATHS | rewrite\_paths |  | Rewrite the paths of the Subgraph errors. If the value is true (default), the paths of the Subgraph errors will be rewritten to match the Schema of the Federated Graph. | true |
| SUBGRAPH\_ERROR\_PROPAGATION\_OMIT\_LOCATIONS | omit\_locations |  | Omit the location field of Subgraph errors. If the value is true, the location field of Subgraph errors will be omitted. | true |
| SUBGRAPH\_ERROR\_PROPAGATION\_OMIT\_EXTENSIONS | omit\_extensions |  | Omit the extensions field of Subgraph errors. If the value is true, the extensions field of Subgraph errors will be omitted. | false |
| SUBGRAPH\_ERROR\_PROPAGATION\_STATUS\_CODES | propagate\_status\_codes |  | Propagate Subgraph status codes. If the value is true, Subgraph Response status codes will be propagated to the client in the errors.extensions.code field. | false |
| SUBGRAPH\_ERROR\_PROPAGATION\_ALLOWED\_FIELDS | allowed\_fields |  | In passthrough mode, by default only message and path is propagated. You can specify additional fields here. |  |
| SUBGRAPH\_ERROR\_PROPAGATION\_DEFAULT\_EXTENSION\_CODE | default\_extension\_code |  | The default extension code. The default extension code is used to specify the default code for the Subgraph errors when the code is not present. | DOWNSTREAM\_SERVICE\_ERROR |
| SUBGRAPH\_ERROR\_PROPAGATION\_ATTACH\_SERVICE\_NAME | attach\_service\_name |  | Attach the service name to each Subgraph error. If the value is true, the service name will be attached to the Subgraph errors. | true |
| SUBGRAPH\_ERROR\_PROPAGATION\_ALLOWED\_EXTENSION\_FIELDS | allowed\_extension\_fields |  | The allowed extension fields. The allowed extension fields are used to specify which fields of the Subgraph errors are allowed to be propagated to the client. | \[“code”\] |
| SUBGRAPH\_ERROR\_PROPAGATION\_ALLOW\_ALL\_EXTENSION\_FIELDS | allow\_all\_extension\_fields |  | Allow all extension fields from Subgraph errors to be propagated to the client. If the value is true (default: false), all extension fields from Subgraph errors will be propagated, overriding the allowed\_extension\_fields configuration. | false |

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-configuration)  Example YAML configuration:

```
version: "1"

subgraph_error_propagation:
  enabled: true
  propagate_status_codes: false
  mode: "wrapped"
  rewrite_paths: true
  omit_locations: true
  omit_extensions: false # If true, overrides allowed_extension_fields and allow_all_extension_fields
  default_extension_code: DOWNSTREAM_SERVICE_ERROR
  attach_service_name: true
  allow_all_extension_fields: false # If true, overrides allowed_extension_fields
  allowed_extension_fields:
    - "code"
```

See [Subgraph Error Propagation](https://cosmo-docs.wundergraph.com/router/subgraph-data-propagation/subgraph-error-propagation) for more detailed information.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#subgraph-extension-propagation)  Subgraph Extension Propagation

The router forwards subgraph response `extensions` to the client. An allow list restricts which extension fields are propagated, and an algorithm selects a winner when multiple subgraphs return the same field.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| SUBGRAPH\_EXTENSION\_PROPAGATION\_ENABLED | enabled |  | Enable forwarding of subgraph response extensions to the client. | false |
| SUBGRAPH\_EXTENSION\_PROPAGATION\_ALLOWED\_EXTENSION\_FIELDS | allowed\_extension\_fields |  | Extension fields that are allowed to be propagated from subgraphs to the client. Any field not in this list is dropped. If empty, all extension fields are forwarded. | \[\] |
| SUBGRAPH\_EXTENSION\_PROPAGATION\_ALGORITHM | algorithm |  | Conflict resolution when multiple subgraphs return the same extension field. `first_write` keeps the value from the first subgraph that wrote it; `last_write` keeps the last. | first\_write |

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-configuration-2)  Example YAML configuration:

```
version: "1"

subgraph_extension_propagation:
  enabled: true
  allowed_extension_fields:
    - rateLimit
    - auth
  algorithm: last_write
```

See [Subgraph Extension Propagation](https://cosmo-docs.wundergraph.com/router/subgraph-data-propagation/subgraph-extension-propagation) for more detailed information.

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#security)  Security

The configuration for the security. The security is used to configure the security settings for the Router.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| SECURITY\_BLOCK\_MUTATIONS | block\_mutations |  | Block mutation Operations. |  |
| SECURITY\_BLOCK\_MUTATIONS\_ENABLED | block\_mutations.enabled |  | If the value is true, the mutations are blocked. | false |
| SECURITY\_BLOCK\_MUTATIONS\_CONDITION | block\_mutations.condition |  | The [expression](https://cosmo-docs.wundergraph.com/router/configuration/template-expressions#authentication-object) to evaluate if the operation should be blocked. |  |
| SECURITY\_BLOCK\_SUBSCRIPTIONS | block\_subscriptions |  | Block subscription Operations. |  |
|  | block\_subscriptions.enabled |  | If the value is true, the subscriptions are blocked. | false |
|  | block\_subscriptions.condition |  | The [expression](https://cosmo-docs.wundergraph.com/router/configuration/template-expressions) to evaluate if the operation should be blocked. |  |
| SECURITY\_BLOCK\_NON\_PERSISTED\_OPERATIONS | block\_non\_persisted\_operations |  | Block non-persisted Operations. |  |
| SECURITY\_BLOCK\_NON\_PERSISTED\_OPERATIONS\_ENABLED | block\_non\_persisted\_operations.enabled |  | If the value is true, the non-persisted operations are blocked. | false |
| SECURITY\_BLOCK\_NON\_PERSISTED\_OPERATIONS\_CONDITION | block\_non\_persisted\_operations.condition |  | The [expression](https://cosmo-docs.wundergraph.com/router/configuration/template-expressions) to evaluate if the operation should be blocked. |  |
| SECURITY\_BLOCK\_PERSISTED\_OPERATIONS | block\_persisted\_operations |  | Block persisted Operations. |  |
| SECURITY\_BLOCK\_PERSISTED\_OPERATIONS\_ENABLED | block\_persisted\_operations.enabled |  | If the value is true, the persisted operations are blocked. | false |
| SECURITY\_BLOCK\_PERSISTED\_OPERATIONS\_CONDITION | block\_persisted\_operations.condition |  | The [expression](https://cosmo-docs.wundergraph.com/router/configuration/template-expressions) to evaluate if the operation should be blocked. |  |
|  | complexity\_calculation\_cache |  | Complexity Cache configuration |  |
|  | complexity\_limits |  | Complexity limits configuration |  |
|  | complexity\_limits.mode |  | `measure` calculates complexity without rejecting; `enforce` rejects operations exceeding limits. | enforce |
| SECURITY\_COMPLEXITY\_IGNORE\_INTROSPECTION | complexity\_limits.ignore\_introspection |  | When true, complexity validation is skipped for all introspection queries. | false |
|  | parser\_limits.approximate\_depth\_limit |  | The approximate cumulative depth limit of a query, including fragments. Set to 0 to disable. | 200 |
|  | parser\_limits.total\_fields\_limit |  | The total number of fields the parser will allow. Set to 0 to disable. | 3500 |
| SECURITY\_OPERATION\_NAME\_LENGTH\_LIMIT | operation\_name\_length\_limit |  | The maximum allowed length for the operation name. Set to 0 to disable. | 512 |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-configuration-2)  Example YAML Configuration

```
version: "1"

security:
  block_mutations:
    enabled: false
    condition: "request.header.Get('x-block-mutation') == 'yes'"
  block_subscriptions:
    enabled: false
  block_non_persisted_operations:
    enabled: false
  block_persisted_operations:
    enabled: false
  complexity_calculation_cache: # This is for a local in-memory cache, to persist the calculation results
    enabled: true
    size: 1024
  complexity_limits:
    mode: enforce # 'measure' calculates complexity without rejecting; 'enforce' rejects operations exceeding limits
    ignore_introspection: false # when true, complexity validation is skipped for all introspection queries
    depth: # the equivalent of `security.depth_limit` previously
      enabled: true
      limit: 7
      ignore_persisted_operations: true
    total_fields:
      enabled: true
      limit: 128
      ignore_persisted_operations: true
    root_fields:
      enabled: true
      limit: 3
      ignore_persisted_operations: true
    root_field_aliases:
      enabled: false
      limit: 3
      ignore_persisted_operations: true
  parser_limits:
    approximate_depth_limit: 300
    total_fields_limit: 700
  operation_name_length_limit: 1024
```

Query Depth is now deprecated. We recommend using the
`security.complexity_calculation_cache` and `security.complexity_limits`
configurations instead, which provide that functionality.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#cost-control)  Cost Control

The configuration for [Cost Control](https://cosmo-docs.wundergraph.com/router/security/cost-control) based on `@cost` and `@listSize` directives.
Calculates estimated and actual costs for GraphQL operations. It can reject expensive operations.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| SECURITY\_COST\_CONTROL\_ENABLED | enabled |  | Enable Cost Control. When true, the router calculates costs for every operation. | false |
| SECURITY\_COST\_CONTROL\_MODE | mode |  | `measure` calculates costs without rejecting; `enforce` rejects operations exceeding the limit. | measure |
| SECURITY\_COST\_CONTROL\_MAX\_ESTIMATED\_LIMIT | max\_estimated\_limit |  | Maximum allowed estimated cost. Operations exceeding this are rejected in enforce mode. 0 means no limit. | 0 |
| SECURITY\_COST\_CONTROL\_ESTIMATED\_LIST\_SIZE | estimated\_list\_size |  | Default assumed size for list fields when no `@listSize` directive is present. Must be positive when enabled. | 0 |
| SECURITY\_COST\_CONTROL\_EXPOSE\_HEADERS | expose\_headers |  | Add `X-WG-Cost-Estimated` and `X-WG-Cost-Actual` response headers. | false |

#### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-configuration-2-2)  Example YAML Configuration

```
security:
  cost_control:
    enabled: true
    mode: enforce
    estimated_list_size: 10
    max_estimated_limit: 1000
    expose_headers: true
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#complexity-calculation-cache)  Complexity Calculation Cache

The configuration for the in-memory complexity cache, to help speed up the calculation process in the event of a recurring query

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| SECURITY\_COMPLEXITY\_CACHE\_ENABLED | enabled |  | Enable the complexity cache | false |
| SECURITY\_COMPLEXITY\_CACHE\_SIZE | size |  | The size of the complexity cache | 1024 |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#complexity-limits)  Complexity Limits

The configuration for adding a complexity limits for queries. We currently expose 4 limits:

- **Query Depth** \- How many nested levels you can have in a query. This limit prevents infinite querying, and also limits the size of the data returned.
- **Total Fields in Query**
- **Root Fields in Query**
- **Root Field Aliases in Query**

A limit is not applied when its value is 0 or `enabled` is not true.The `mode` field controls enforcement versus measurement:

- `measure`: calculates complexity and reports it via telemetry but does not reject requests.
- `enforce` (default): rejects requests that exceed limits.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | mode |  | `measure` calculates complexity without rejecting; `enforce` rejects operations exceeding limits. | enforce |
|  | enabled |  | Enable the specific limit. If the value is true (default: false), and a valid limit value is set, the limit will be applied. | false |
|  | limit |  | The limit amount for query. If the limit is 0, this limit is not applied. | 0 |
|  | ignore\_persisted\_operations |  | Disable the limit for persisted operations. Since persisted operations are stored intentionally, users may want to disable the limit to consciously allow nested persisted operations. | false |

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#file-upload)  File Upload

The configuration for file upload. Configure whether it should be enabled along with file size and number of files.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| FILE\_UPLOAD\_ENABLED | enabled |  | Whether the feature is enabled or not | true |
| FILE\_UPLOAD\_MAX\_FILE\_SIZE | max\_file\_size |  | The maximum size of a file that can be uploaded. The size is specified as a string with a number and a unit, e.g. 10KB, 1MB, 1GB. The supported units are ‘KB’, ‘MB’, ‘GB’. | 50MB |
| FILE\_UPLOAD\_MAX\_FILES | max\_files |  | The maximum number of files that can be uploaded per request. | 2 |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-configuration-3)  Example YAML Configuration

```
version: "1"

file_upload:
  enabled: true
  max_file_size: 1GB
  max_files: 2
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#client-header)  Client Header

The configuration for custom names for client name and client version headers.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | name |  | The custom name of the client name header. |  |
|  | version |  | The custom name of the client version header. |  |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-configuration-4)  Example YAML Configuration

```
version: "1"

client_header:
  name: "Client-Name"
  version: "Client-Version"
```

By default, we support `Graphql-Client-Name` , `Graphql-Client-Version`, `ApolloGraphql-Client-Name`, `ApolloGraphql-Client-Version`.The custom names are given more precedence.

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#apollo-compatibility-flags)  Apollo Compatibility Flags

This configuration is used to enable full compatibility with Apollo Federation, Apollo Gateway and Apollo Router, you can enable certain compatibility flags, allowing you to use Cosmo Router as a drop-in replacement for Apollo.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#apollo-compatibility-value-completion)  Apollo Compatibility Value Completion

Invalid \_\_typename values will be returned in extensions.valueCompletion instead of errors.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#apollo-compatibility-truncate-floats)  Apollo Compatibility Truncate Floats

Truncate floats like 1.0 to 1, 2.0 to 2, etc.. Values like 1.1 or 2.2 will not be truncated.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#apollo-compatibility-suppress-fetch-errors)  Apollo Compatibility Suppress Fetch Errors

Suppresses fetch errors. When enabled, only the ‘data’ object is returned, suppressing errors. If disabled, fetch errors are included in the ‘errors’ array.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#apollo-compatibility-replace-undefined-op-field-errors-deprecated)  Apollo Compatibility Replace Undefined Op Field Errors (Deprecated)

This flag is deprecated. Use `use_graphql_validation_failed_status` instead.

Produces the same error message as Apollo when an invalid operation field is included in an operation selection set. **Extension code**: “GRAPHQL\_VALIDATION\_FAILED” Status code: 400

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#apollo-compatibility-use-graphql-validation-failed-status)  Apollo Compatibility Use GraphQL Validation Failed Status

Produces the same error message and status as Apollo when GraphQL validation fails. **Extension code**: “GRAPHQL\_VALIDATION\_FAILED” Status code: 400

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#apollo-compatibility-replace-invalid-var-errors)  Apollo Compatibility Replace Invalid Var Errors

Produces the same error message as Apollo when an invalid variable is supplied. **Extension code**: “BAD\_USER\_INPUT”

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#apollo-compatibility-replace-validation-error-status)  Apollo Compatibility Replace Validation Error Status

Produces the same error status as Apollo when validation fails. **Error status**: 400 Bad Request **Minimum router version**: [0.175.0](https://github.com/wundergraph/cosmo/compare/router@0.174.3...router@0.175.0)

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| APOLLO\_COMPATIBILITY\_ENABLE\_ALL | apollo\_compatibility\_flags: enable\_all: <bool> |  | Enables all the options of Apollo Compatibility. | false |
| APOLLO\_COMPATIBILITY\_VALUE\_COMPLETION\_ENABLED | value\_completion: enabled: <bool> |  | Enables value completion. | false |
| APOLLO\_COMPATIBILITY\_TRUNCATE\_FLOATS\_ENABLED | truncate\_floats: enabled: <bool> |  | Enables truncate floats. | false |
| APOLLO\_COMPATIBILITY\_SUPPRESS\_FETCH\_ERRORS\_ENABLED | suppress\_fetch\_errors: enabled: <bool> |  | Enables suppress fetch errors. | false |
| APOLLO\_COMPATIBILITY\_REPLACE\_UNDEFINED\_OP\_FIELD\_ERRORS\_ENABLED | replace\_undefined\_op\_field\_errors: enabled: <bool> |  | **Deprecated**. Replaces undefined operation field errors. Use use\_graphql\_validation\_failed\_status instead. | false |
| APOLLO\_COMPATIBILITY\_REPLACE\_INVALID\_VAR\_ERRORS\_ENABLED | replace\_invalid\_var\_errors: enabled: <bool> |  | Replaces invalid variable errors. | false |
| APOLLO\_COMPATIBILITY\_REPLACE\_VALIDATION\_ERROR\_STATUS\_ENABLED | replace\_validation\_error\_status: enabled: <bool> |  | Replaces validation error status with 400. | false |
| APOLLO\_COMPATIBILITY\_SUBSCRIPTION\_MULTIPART\_PRINT\_BOUNDARY\_ENABLED | subscription\_multipart\_print\_boundary: enabled: <bool> |  | Prints the multipart boundary right after the message in multipart subscriptions. Without this flag, the Apollo client wouldn’t parse a message until the next one is pushed. | false |
| APOLLO\_COMPATIBILITY\_USE\_GRAPHQL\_VALIDATION\_FAILED\_STATUS\_ENABLED | use\_graphql\_validation\_failed\_status: enabled: <bool> |  | Uses GraphQL validation failed status code and error format. | false |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-configuration-5)  Example YAML Configuration

```
version: "1"

apollo_compatibility_flags:
  enable_all: false
  value_completion:
    enabled: true
  truncate_floats:
    enabled: false
  suppress_fetch_errors:
    enabled: true
  replace_undefined_op_field_errors:
    enabled: true # Deprecated, use use_graphql_validation_failed_status instead
  replace_invalid_var_errors:
    enabled: true
  replace_validation_error_status:
    enabled: false
  subscription_multipart_print_boundary:
    enabled: false
  use_graphql_validation_failed_status:
    enabled: true
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#apollo-router-compatibility-flags)  Apollo Router Compatibility Flags

Apollo Router Compatibility Flags _can_ be enabled alongside Apollo
Compatibility Flags, but some will override their counterpart’s functionality.
This means you can safely use `enable_all: true` alongside these flags.

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#apollo-router-compatibility-replace-invalid-var-errors)  Apollo Router Compatibility Replace Invalid Var Errors

Produces the same error messages as Apollo Router when an invalid variable is supplied.Extension code: “VALIDATION\_INVALID\_TYPE\_VARIABLE”

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| APOLLO\_ROUTER\_COMPATIBILITY\_REPLACE\_INVALID\_VAR\_ERRORS\_ENABLED | replace\_invalid\_var\_errors |  | Replaces invalid variable errors. | false |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#apollo-router-compatibility-skip-null-variables-error)  Apollo Router Compatibility Skip Null Variables Error

Skips the validation error raised when `null` is supplied for a variable of a non-nullable type, matching Apollo Router behavior. Variables that are missing entirely still produce an error.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| APOLLO\_ROUTER\_COMPATIBILITY\_SKIP\_NULL\_VARIABLES\_ERROR\_ENABLED | skip\_null\_variables\_error |  | Skips the error when a null variable is supplied for a non-nullable type. | false |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-configuration-6)  Example YAML Configuration

```
version: "1"

apollo_router_compatibility_flags:
  replace_invalid_var_errors:
    enabled: true
  skip_null_variables_error:
    enabled: true
```

## [​](https://cosmo-docs.wundergraph.com/router/configuration\#cache-warmer)  Cache warmer

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
| CACHE\_WARMUP\_ENABLED | enabled |  | Enable the cache warmer. | false |
| CACHE\_WARMUP\_ITEMS\_PER\_SECOND | items\_per\_second |  | Maximum number of cache warmup items processed per second across all workers. Acts as an upper bound: actual throughput can be lower if processing is slow or there are too few items. Set to `0` for unlimited. Higher numbers decrease warmup time but increase system load. | 50 |
| CACHE\_WARMUP\_ITEM\_DELAY | item\_delay |  | A fixed delay applied after each cache warmup item is processed, per worker. Use to further smooth load during warmup. It applies in addition to `items_per_second`. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’. | 0s |
| CACHE\_WARMUP\_TIMEOUT | timeout |  | The timeout for warming up the cache. This can be used to limit the amount of time cache warming will block deploying a new config. The period is specified as a string with a number and a unit, e.g. 10ms, 1s, 1m, 1h. The supported units are ‘ms’, ‘s’, ‘m’, ‘h’. | 30s |
| CACHE\_WARMUP\_WORKERS | workers |  | The number of workers for the cache warmup to run in parallel. Higher numbers decrease the time to warm up the cache but increase the load on the system. | 8 |
|  | source |  | The source of the cache warmup items. Only one can be specified. If empty, the cache warmup source is the Cosmo CDN and it requires a graph to be set. |  |
| CACHE\_WARMUP\_IN\_MEMORY\_FALLBACK | in\_memory\_fallback |  | Enable in-memory switchover that persists the plan cache across router restarts. When enabled, the router will use queries from the previous instance’s plan cache to warm up the new cache on restart. Can be used as a fallback or as the primary source for cache warming. | true |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-36)  Example YAML config:

config.yaml

```
version: "1"

cache_warmup:
  enabled: true
  workers: 8
  items_per_second: 50
  item_delay: 0s
  timeout: 30s
  in_memory_fallback: true
```

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#source)  Source

The source of the cache warmup items. Only one can be specified. If empty, the cache warmup source is the Cosmo CDN and it requires a graph to be set.

| Environment Variable | YAML | Required | Description | Default Value |
| --- | --- | --- | --- | --- |
|  | filesystem.path |  | The path to the directory containing the cache warmup items. |  |
|  | cdn.enabled |  | Whether the CDN is the source for warming the cache. | true |

### [​](https://cosmo-docs.wundergraph.com/router/configuration\#example-yaml-config-37)  Example YAML config:

config.yaml

```
version: "1"

cache_warmup:
  enabled: true
  workers: 8
  items_per_second: 50
  item_delay: 0s
  timeout: 30s
  in_memory_fallback: true
  source:
    cdn:
      enabled: true
    filesystem:
      path: "./cache-warmer/operations"
```

Was this page helpful?

YesNo

[Download & Install](https://cosmo-docs.wundergraph.com/router/download-and-install) [Configuration Design](https://cosmo-docs.wundergraph.com/router/configuration/config-design)

Ctrl+I

Assistant

Responses are generated using AI and may contain mistakes.