--- title: Configure Optimizely Agent slug: feature-experimentation/docs/configure-optimizely-agent docTags: createdAt: 2026-08-05T20:40:03.000Z --- Optimizely Agent uses the configuration file in the active directory by default. For example, `./config.yaml`. You can override the [default configuration](https://github.com/optimizely/agent/blob/master/config.yaml) by providing a YAML configuration file at runtime. You can specify alternative configuration locations at runtime using an environment variable or command line flag: ```shell OPTIMIZELY_CONFIG_FILENAME=newconfig.yaml make run ``` You must configure [Real-Time Audiences for Feature Experimentation](docId:6UBBxxRv331nBIVZ2lun8) to use the following properties: - `OPTIMIZELY_CLIENT_ODP_DISABLE` - `OPTIMIZELY_CLIENT_ODP_EVENTSREQUESTTIMEOUT` - `OPTIMIZELY_CLIENT_ODP_EVENTSFLUSHINTERVAL` - `OPTIMIZELY_CLIENT_ODP_SEGMENTSREQUESTTIMEOUT` - `OPTIMIZELY_CLIENT_ODP_SEGMENTSCACHE` The following is a comprehensive list of available configuration properties. | Property Name | Env Variable | Description | | --------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `admin.auth.clients` | N/A | Credentials for requesting access tokens. See [Authorization Guide](docId:8qP1vJL67JdMucq3g9VQU). | | `admin.auth.hmacSecrets` | OPTIMIZELY\_ADMIN\_AUTH\_HMACSECRETS | Signing secret for issued access tokens. See [Authorization Guide](docId:8qP1vJL67JdMucq3g9VQU). | | `admin.auth.jwksUpdateInterval` | OPTIMIZELY\_ADMIN\_AUTH\_JWKSUPDATEINTERVAL | JWKS Update Interval for caching the keys in the background. See [Authorization Guide](docId:8qP1vJL67JdMucq3g9VQU). | | `admin.auth.jwksURL` | OPTIMIZELY\_ADMIN\_AUTH\_JWKSURL | JWKS URL for validating access tokens. See [Authorization Guide](docId:8qP1vJL67JdMucq3g9VQU). | | `admin.auth.ttl` | OPTIMIZELY\_ADMIN\_AUTH\_TTL | Time-to-live of issued access tokens. See [Authorization Guide](docId:8qP1vJL67JdMucq3g9VQU). | | `admin.port` | OPTIMIZELY\_ADMIN\_PORT | Admin listener port. Default: `8088`. | | `api.auth.clients` | N/A | Credentials for requesting access tokens. See [Authorization Guide](docId:8qP1vJL67JdMucq3g9VQU). | | `api.auth.hmacSecrets` | OPTIMIZELY\_API\_AUTH\_HMACSECRETS | Signing secret for issued access tokens. See [Authorization Guide](docId:8qP1vJL67JdMucq3g9VQU). | | `api.auth.jwksUpdateInterval` | OPTIMIZELY\_API\_AUTH\_JWKSUPDATEINTERVAL | JWKS Update Interval for caching the keys in the background. See [Authorization Guide](docId:8qP1vJL67JdMucq3g9VQU). | | `api.auth.jwksURL` | OPTIMIZELY\_API\_AUTH\_JWKSURL | JWKS URL for validating access tokens. See [Authorization Guide](docId:8qP1vJL67JdMucq3g9VQU). | | `api.auth.ttl` | OPTIMIZELY\_API\_AUTH\_TTL | Time-to-live of issued access tokens. See [Authorization Guide](docId:8qP1vJL67JdMucq3g9VQU). | | `api.enableNotifications` | OPTIMIZELY\_API\_ENABLENOTIFICATIONS | Enable streaming notification endpoint. Default: false | | `api.enableOverrides` | OPTIMIZELY\_API\_ENABLEOVERRIDES | Enable bucketing overrides endpoint. Default: false | | `api.maxConns` | OPTIMIZELY\_API\_MAXCONNS | Maximum number of concurrent requests | | `api.port` | OPTIMIZELY\_API\_PORT | Api listener port. Default: `8080`. | | `author` | OPTIMIZELY\_AUTHOR | Agent author. Default: `Optimizely Inc.`. | | `client.batchSize` | OPTIMIZELY\_CLIENT\_BATCHSIZE | The number of events in a batch. Default: `10`. | | `client.datafileURLTemplate` | OPTIMIZELY\_CLIENT\_DATAFILEURLTEMPLATE | Template URL for SDK datafile location. Default: `` | | `client.eventURL` | OPTIMIZELY\_CLIENT\_EVENTURL | URL for dispatching events. Default: `` | | `client.flushInterval` | OPTIMIZELY\_CLIENT\_FLUSHINTERVAL | The maximum time between events being dispatched. Default: `30s`. | | `client.pollingInterval` | OPTIMIZELY\_CLIENT\_POLLINGINTERVAL | The time between successive polls for updated project configuration. Default: `1m`. | | `client.queueSize` | OPTIMIZELY\_CLIENT\_QUEUESIZE | The max number of events pending dispatch. Default: `1000`. | | `client.sdkKeyRegex` | OPTIMIZELY\_CLIENT\_SDKKEYREGEX | Regex to validate SDK keys provided in request header. Default: `^[a-zA-Z0-9+/=_]+(:[a-zA-Z0-9+/=_]+)?$`. | | `client.userProfileService` | OPTIMIZELY\_CLIENT\_USERPROFILESERVICE | Property used to enable and set `UserProfileServices`. Default: `./config.yaml`. | | `client.odp.disable` | OPTIMIZELY\_CLIENT\_ODP\_DISABLE | Property used to disable odp. Default: `false`. | | `client.odp.eventsRequestTimeout` | OPTIMIZELY\_CLIENT\_ODP\_EVENTSREQUESTTIMEOUT | Property used to update timeout in seconds after which event requests will timeout. Default: `10`s. | | `client.odp.eventsFlushInterval` | OPTIMIZELY\_CLIENT\_ODP\_EVENTSFLUSHINTERVAL | Property used to update flush interval in seconds for events. Default: `1`s. | | `client.odp.segmentsRequestTimeout` | OPTIMIZELY\_CLIENT\_ODP\_SEGMENTSREQUESTTIMEOUT | Property used to update timeout in seconds after which audience segment requests timeout. Default: 10s | | `client.odp.cache` | OPTIMIZELY\_CLIENT\_ODP\_SEGMENTSCACHE | Property used to enable and set cache service for odp. Default: `./config.yaml`. | | `config.filename` | OPTIMIZELY\_CONFIG\_FILENAME | Location of the configuration YAML file. Default: `./config.yaml`. | | `log.level` | OPTIMIZELY\_LOG\_LEVEL | The log [level](https://github.com/rs/zerolog#leveled-logging) for the agent. Default: `info`. | | `log.pretty` | OPTIMIZELY\_LOG\_PRETTY | Flag used to set colorized console output as opposed to structured json logs. Default: `false`. | | `name` | OPTIMIZELY\_NAME | Agent name. Default: `optimizely`. | | `sdkKeys` | OPTIMIZELY\_SDKKEYS | Comma delimited list of SDK keys used to initialize on startup. | | `server.allowedHosts` | OPTIMIZELY\_SERVER\_ALLOWEDHOSTS | List of allowed request host values. Requests whose host value does not match either the configured server.host, or one of these, is rejected with a 404 response. To match all subdomains, you can use a leading dot (for example `.example.com` matches `my.example.com`, `hello.world.example.com`, and so on). You can use the value `.` to disable allowed host checking, allowing requests with any host. Request host is determined in the following priority order: 1. X-Forwarded-Host header value, 2. Forwarded header host= directive value, 3. Host property of request (see Host under [https://pkg.go.dev/net/http#Request](https://pkg.go.dev/net/http#Request)). Note: do not include port in these hosts values - port is stripped from the request host before comparing against these. | | `server.batchRequests.maxConcurrency` | OPTIMIZELY\_SERVER\_BATCHREQUESTS\_MAXCONCURRENCY | Number of requests running in parallel. Default: `10`. | | `server.batchRequests.operationsLimit` | OPTIMIZELY\_SERVER\_BATCHREQUESTS\_OPERATIONSLIMIT | Number of allowed operations. (will flag an error if the number of operations exceeds this parameter) Default: `500`. | | `server.certfile` | OPTIMIZELY\_SERVER\_CERTFILE | Path to a certificate file, used to run Agent with HTTPS. | | `server.disabledCiphers` | OPTIMIZELY\_SERVER\_DISABLEDCIPHERS | List of TLS ciphers to disable when accepting HTTPS connections. | | `server.healthCheckPath` | OPTIMIZELY\_SERVER\_HEALTHCHECKPATH | Path for the health status api. Default: `/health`. | | `server.host` | OPTIMIZELY\_SERVER\_HOST | Host of server. Default: `127.0.0.1`. | | `server.interceptors` | N/A | Property used to enable and set [Interceptor](docId\:FBkIiB4shao_1U30W5cAu) plugins | | `server.keyfile` | OPTIMIZELY\_SERVER\_KEYFILE | Path to a key file, used to run Agent with HTTPS | | `server.readTimeout` | OPTIMIZELY\_SERVER\_READTIMEOUT | The maximum duration for reading the entire body. Default: `5s` | | `server.writeTimeout` | OPTIMIZELY\_SERVER\_WRITETIMEOUT | The maximum duration before timing out writes of the response. Default: `10s` | | `version` | OPTIMIZELY\_VERSION | Agent version. Default: `git describe --tags`. | | `webhook.port` | OPTIMIZELY\_WEBHOOK\_PORT | Webhook listener port: Default: `8089`. | | `webhook.projects.<_projectId_>.sdkKeys` | N/A | Comma-delimited list of SDK Keys applicable to the respective `projectId`. | | `webhook.projects.<_projectId_>.secret` | N/A | Webhook secret used to validate webhook requests originating from the respective `projectId`. | | `webhook.projects.<_projectId_>.skipSignatureCheck` | N/A | Boolean to indicate whether the signature should be validated. | Information about configuring Agent can be found in the [Agent advanced configuration document](docId\:zHCNhlVgfvKUzQc4LKNN1). To use a `PROXY` server the following environment variables can be used: | Environment variable | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------- | | `HTTP_PROXY` | HTTP URL of the proxy server to use for every request. | | `HTTPS_PROXY` | HTTPS URL of the proxy server to use for every request. It takes precedence over HTTP\_PROXY for HTTPS requests. | | `NO_PROXY` | Defines that no proxy should be used. | The environment values may be a complete URL or a `host[:port]`, in which case the `http` scheme is assumed. The schemes `http`, `https`, and `socks5` are supported. To read more about proxy configurations, see the [Go documentation on net/http](https://pkg.go.dev/net/http#ProxyFromEnvironment).