Dev guideAPI Reference
Dev guideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In

Configure Optimizely Agent

How to configure Optimizely Agent with a comprehensive list of available configuration properties.

By default, Optimizely Agent uses the configuration file in the current active directory. For example, ./config.yaml. You can override the default configuration by providing a YAML configuration file at runtime.

You can specify alternative configuration locations at runtime via an environment variable or command line flag:

OPTIMIZELY_CONFIG_FILENAME=newconfig.yaml make run



You must set up the Advanced Audience Targeting integration enabled to use


The Advanced Audience Targeting integration is currently in beta. Contact your Customer Success Manager for more information or register now on

Below is a comprehensive list of available configuration properties.

Property NameEnv VariableDescription
admin.auth.clientsN/ACredentials for requesting access tokens. See: Authorization Guide
admin.auth.hmacSecretsOPTIMIZELY_ADMIN_AUTH_HMACSECRETSSigning secret for issued access tokens. See: Authorization Guide
admin.auth.jwksUpdateIntervalOPTIMIZELY_ADMIN_AUTH_JWKSUPDATEINTERVALJWKS Update Interval for caching the keys in the background. See: Authorization Guide
admin.auth.jwksURLOPTIMIZELY_ADMIN_AUTH_JWKSURLJWKS URL for validating access tokens. See: Authorization Guide
admin.auth.ttlOPTIMIZELY_ADMIN_AUTH_TTLTime-to-live of issued access tokens. See: Authorization Guide
admin.portOPTIMIZELY_ADMIN_PORTAdmin listener port. Default: 8088
api.auth.clientsN/ACredentials for requesting access tokens. See: Authorization Guide
api.auth.hmacSecretsOPTIMIZELY_API_AUTH_HMACSECRETSSigning secret for issued access tokens. See: Authorization Guide
api.auth.jwksUpdateIntervalOPTIMIZELY_API_AUTH_JWKSUPDATEINTERVALJWKS Update Interval for caching the keys in the background. See: Authorization Guide
api.auth.jwksURLOPTIMIZELY_API_AUTH_JWKSURLJWKS URL for validating access tokens. See: Authorization Guide
api.auth.ttlOPTIMIZELY_API_AUTH_TTLTime-to-live of issued access tokens. See: Authorization Guide
api.enableNotificationsOPTIMIZELY_API_ENABLENOTIFICATIONSEnable streaming notification endpoint. Default: false
api.enableOverridesOPTIMIZELY_API_ENABLEOVERRIDESEnable bucketing overrides endpoint. Default: false
api.maxConnsOPTIMIZELY_API_MAXCONNSMaximum number of concurrent requests
api.portOPTIMIZELY_API_PORTApi listener port. Default: 8080
authorOPTIMIZELY_AUTHORAgent author. Default: Optimizely Inc.
client.batchSizeOPTIMIZELY_CLIENT_BATCHSIZEThe number of events in a batch. Default: 10
client.datafileURLTemplateOPTIMIZELY_CLIENT_DATAFILEURLTEMPLATETemplate URL for SDK datafile location. Default:
client.eventURLOPTIMIZELY_CLIENT_EVENTURLURL for dispatching events. Default:
client.flushIntervalOPTIMIZELY_CLIENT_FLUSHINTERVALThe maximum time between events being dispatched. Default: 30s
client.pollingIntervalOPTIMIZELY_CLIENT_POLLINGINTERVALThe time between successive polls for updated project configuration. Default: 1m
client.queueSizeOPTIMIZELY_CLIENT_QUEUESIZEThe max number of events pending dispatch. Default: 1000
client.sdkKeyRegexOPTIMIZELY_CLIENT_SDKKEYREGEXRegex to validate SDK keys provided in request header. Default: ^\w+(:\w+)?$
client.userProfileServiceOPTIMIZELY_CLIENT_USERPROFILESERVICEProperty used to enable and set UserProfileServices. Default: ./config.yaml
client.odp.disableOPTIMIZELY_CLIENT_ODP_DISABLEProperty used to disable odp. Default: false
client.odp.eventsRequestTimeoutOPTIMIZELY_CLIENT_ODP_EVENTSREQUESTTIMEOUTProperty used to update timeout in seconds after which event requests will timeout. Default: 10s
client.odp.eventsFlushIntervalOPTIMIZELY_CLIENT_ODP_EVENTSFLUSHINTERVALProperty used to update flush interval in seconds for events. Default: 1s
client.odp.segmentsRequestTimeoutOPTIMIZELY_CLIENT_ODP_SEGMENTSREQUESTTIMEOUTProperty used to update timeout in seconds after which segment requests will timeout. Default: 10s
client.odp.cacheOPTIMIZELY_CLIENT_ODP_SEGMENTSCACHEProperty used to enable and set cache service for odp. Default: ./config.yaml
config.filenameOPTIMIZELY_CONFIG_FILENAMELocation of the configuration YAML file. Default: ./config.yaml
log.levelOPTIMIZELY_LOG_LEVELThe log level for the agent. Default: info
log.prettyOPTIMIZELY_LOG_PRETTYFlag used to set colorized console output as opposed to structured json logs. Default: false
nameOPTIMIZELY_NAMEAgent name. Default: optimizely
sdkKeysOPTIMIZELY_SDKKEYSComma delimited list of SDK keys used to initialize on startup
server.allowedHostsOPTIMIZELY_SERVER_ALLOWEDHOSTSList of allowed request host values. Requests whose host value does not match either the configured, or one of these, will be rejected with a 404 response. To match all subdomains, you can use a leading dot (for example matches,, etc.). 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 Note: don't include port in these hosts values - port is stripped from the request host before comparing against these.
server.batchRequests.maxConcurrencyOPTIMIZELY_SERVER_BATCHREQUESTS_MAXCONCURRENCYNumber of requests running in parallel. Default: 10
server.batchRequests.operationsLimitOPTIMIZELY_SERVER_BATCHREQUESTS_OPERATIONSLIMITNumber of allowed operations. ( will flag an error if the number of operations exeeds this parameter) Default: 500
server.certfileOPTIMIZELY_SERVER_CERTFILEPath to a certificate file, used to run Agent with HTTPS
server.disabledCiphersOPTIMIZELY_SERVER_DISABLEDCIPHERSList of TLS ciphers to disable when accepting HTTPS connections
server.healthCheckPathOPTIMIZELY_SERVER_HEALTHCHECKPATHPath for the health status api. Default: /health
server.hostOPTIMIZELY_SERVER_HOSTHost of server. Default:
server.interceptorsN/AProperty used to enable and set Interceptor plugins
server.keyfileOPTIMIZELY_SERVER_KEYFILEPath to a key file, used to run Agent with HTTPS
server.readTimeoutOPTIMIZELY_SERVER_READTIMEOUTThe maximum duration for reading the entire body. Default: ā€œ5sā€
server.writeTimeoutOPTIMIZELY_SERVER_WRITETIMEOUTThe maximum duration before timing out writes of the response. Default: ā€œ10sā€
versionOPTIMIZELY_VERSIONAgent version. Default: git describe --tags
webhook.portOPTIMIZELY_WEBHOOK_PORTWebhook listener port: Default: 8085
webhook.projects.<projectId>.sdkKeysN/AComma delimited list of SDK Keys applicable to the respective projectId
webhook.projects.<projectId>.secretN/AWebhook secret used to validate webhook requests originating from the respective projectId
webhook.projects.<projectId>.skipSignatureCheckN/ABoolean to indicate whether the signature should be validated. TODO remove in favor of empty secret.

More information about configuring Agent can be found in the Advanced Configuration Notes.

To use a PROXY server the following environment variables can be used:

Environment variableDescription
HTTP_PROXYHTTP URL of the proxy server to use for every request.
HTTPS_PROXYHTTPS URL of the proxy server to use for every request. It takes precedence over HTTP_PROXY for HTTPS requests.
NO_PROXYDefines that no proxy should be used.

The environment values may be either 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, view the Go documentation on net/http.