Deploy Relay Proxy

Updated 3 days ago by Clare Wilkinson

This topic describes how to deploy and start the Relay Proxy.

Before You Begin


  • When the Proxy starts up, if an API key does not exist in Feature Flags, the Proxy will not be able to validate that API key during Authentication. Because the Proxy only retrieves API keys at startup and does not check for new ones.
  • If you start the proxy and then later create a new API key in Feature Flags, you must restart the proxy and pass the new API key in its configuration.

Configure Relay Proxy

You can start the Relay Proxy by pulling the harness/ff-proxy image from Docker.

  1. Pull the latest Relay Proxy Docker image.

    docker pull harness/ff-proxy
  2. View the configuration variables by running the following command:

    docker run harness/ff-proxy

    This prints all the configuration variables.
    Details of /app/ff-proxy Configuration variables:

    account-identifier string

    An account identifier to load remote config

    admin-service string

    The URL of the ff admin service (default

    admin-service-token string

    Token to use with the ff service

    api-keys value

    API keys to connect with ff-server for each environment

     auth-secret string

    The secret used for signing auth tokens


    Bypasses authentication

    client-service string

    The URL of the ff client service (default


    Enables debug logging


    Enables side loading of data from the config directory

    org-identifier string

    An org identifier to load remote config

    port int

    Port that the proxy service is exposed on (default 7000)

    redis-address string

    Redis host:port address

    redis-db int

    Database to be selected after connecting to the server

    redis-password string

    (Optional) Redis password

    sdk-base-url string

    URL for the SDK to connect to (default

    sdk-events-url string

    URL for the SDK to send metrics to (default

    The Relay Proxy obtains a list of all Environments and associated API keys for the given Account and Organization when it first starts up, which it will use to validate authentication requests and generate tokens.

    The following are the required configuration variables to connect to the Feature Flags service:
    • admin-service-token: Enter the Service Account details. An auth token that lets the proxy communicate with Feature Flags. For more information on how to create a Service Account, see Create a Service Account.
    • account-identifier: Enter your account identifier for which you want to retrieve the config. You can copy the account ID from the Harness Manager. In Harness Manager's address bar, copy the Harness account ID from your Harness URL. The Harness account ID comes after account in the URL. For example in the following URL, the account ID is 1a2b3c
    • org-identifier: Enter your organization identifier for which you want to retrieve the config. For more information, see Create a Harness Organization.
    • api-keys: Enter you server SDK key. For more information, see Add and Manage API Keys.
    • auth-secret: Enter your authentication secret details. A secret that is used by the proxy to sign the JWTs that it sends to the SDKs. For more information, see Add a Secrets Manager.
  3. Specify your configuration details and Docker run the proxy image. The following are the examples:
    1. Here is an example of a Docker Relay Proxy image with the required configuration details:

      docker run -d -p 7000:7000 harness/ff-proxy -admin-service-token $MY_SERVICE_TOKEN -account-identifier $MY_ACCOUNT_IDENTIFIER -org-identifier $MY_ORG_IDENTIFIER -api-keys $ENV_1_KEY,$ENV_2_KEY,$ENV_3_KEY... -auth-secret $ANY_AUTH_SECRET
    2. The following example uses a .env file. Create a .env file with the following environment variables:

      // Create a .env file with these envs 

      Then use the .env file with docker run

      docker run -d -p 7000:7000 --env-file .env harness/ff-proxy
  4. (Optional) You can optionally provide config for a Redis instance used to store flag data using the redis-address, redis-db (optional), and redis-password (optional).
    If you do not use Redis, the flag data is stored in the memory. In-memory is the default option.

Configure SDKs to Work With the Relay Proxy

The SDKs do not require any additional configuration to work with the proxy. The only difference is that instead of supplying the Feature Flags URL when starting up an SDK, you should pass the proxy URL.

For example, if you wanted your SDK to go via QA without the Proxy, you'd give it the following URLs:



But if you have a Proxy running locally on localhost:7000 and it’s connected to QA then pass the following URLs to the SDK:

baseURL:   http://localhost:7000

eventsURL: http://localhost:7000

SDK Examples With Relay Proxy

The following examples show how to point an SDK at the Relay Proxy:


proxyURL := "http://localhost:7000"
apiKey := "your API Key"

target := dto.NewTargetBuilder("your-target").

client, err := harness.NewCfClient(apiKey,
if err != nil {


String proxyURL = "http://localhost:7000";

config = Config.Builder()

await CfClient.Instance.Initialize(API_KEY, config);

* Define you target on which you would like to evaluate
* the featureFlag
Target target =
.Name("User1") //can change with your target name
.Identifier("[email protected]") //can change with your target identifier

JavaScript SDK

apiKey = "your API Key"
proxyURL = "http://localhost:7000"

var cf = initialize(apiKey,
baseUrl: proxyURL,
eventUrl: proxyURL,

Configure Relay Proxy with Redis

You can run Redis locally and configure the Proxy to work with it. Perform the following steps to configure Proxy with Redis.

  1. Start Redis.

     docker run --rm --name redis -d -p 6379:6379 redis:latest
  2. Start the Proxy and configure using a .env.

     docker run -d -p 7000:7000 --env-file .online.uat.env harness/ff-proxy:latest
  3. Start the Proxy and configure using flags.

    docker run -d -p 7000:7000 harness/ff-proxy -redis-address $REDIS_ADDRESS -admin-service-token $MY_SERVICE_TOKEN -account-identifier $MY_ACCOUNT_IDENTIFIER -org-identifier $MY_ORG_IDENTIFIER -api-keys $ENV_1_KEY,$ENV_2_KEY,$ENV_3_KEY... -auth-secret $ANY_AUTH_SECRET

Please Provide Feedback