Dev guideAPI Reference
Dev guideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Configure Optimizely Agent

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

Optimizely Agent uses the configuration file in the active directory by default. 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 using an environment variable or command line flag:

OPTIMIZELY_CONFIG_FILENAME=newconfig.yaml make run

You must configure Real-Time Segments for Feature Experimentation to use:


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: do not 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.

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.