Skip to main content

Unleash Edge

Generated content

This document was generated from the README in the Unleash Edge GitHub repository.

🏗️ Under construction!

Unleash Edge is currently considered very experimental. Use it at your own risk.

Share your comments in 🗣️ GitHub Discussions or the 💬 Unleash community Slack.

Unleash Edge Documentation MIT licensed Dependency Status CI Coverage Status downloads

Unleash Edge is the successor to the Unleash Proxy.

Unleash Edge sits between the Unleash API and your SDKs and provides a cached read-replica of your Unleash instance. This means you can scale up your Unleash instance to thousands of connected SDKs without increasing the number of requests you make to your Unleash instance.

Unleash Edge offers two important features:

  • Performance: Unleash Edge caches in memory and can run close to your end-users. A single instance can handle tens to hundreds of thousands of requests per second.
  • Resilience: Unleash Edge is designed to survive restarts and operate properly even if you lose connection to your Unleash server.

Unleash Edge is built to help you scale Unleash, if you're looking for the easiest way to connect your client SDKs you can check out our Frontend API.

Running Unleash Edge

Unleash Edge is compiled to a single binary. You can configure it by passing in arguments or setting environment variables.

Usage: unleash-edge [OPTIONS] <COMMAND>

edge Run in edge mode
offline Run in offline mode
help Print this message or the help of the given subcommand(s)

-p, --port <PORT>
Which port should this server listen for HTTP traffic on [env: PORT=] [default: 3063]
-i, --interface <INTERFACE>
Which interfaces should this server listen for HTTP traffic on [env: INTERFACE=] [default:]
-w, --workers <WORKERS>
How many workers should be started to handle requests. Defaults to number of physical cpus [env: WORKERS=] [default: number of physical cpus]
Should we bind TLS [env: TLS_ENABLE=]
--tls-server-key <TLS_SERVER_KEY>
Server key to use for TLS [env: TLS_SERVER_KEY=]
--tls-server-cert <TLS_SERVER_CERT>
Server Cert to use for TLS [env: TLS_SERVER_CERT=]
--tls-server-port <TLS_SERVER_PORT>
Port to listen for https connection on (will use the interfaces already defined) [env: TLS_SERVER_PORT=] [default: 3043]
--instance-id <INSTANCE_ID>
Instance id. Used for metrics reporting [env: INSTANCE_ID=] [default: Ulid::new()]
-a, --app-name <APP_NAME>
App name. Used for metrics reporting [env: APP_NAME=] [default: unleash-edge]
-h, --help
Print help

Getting Unleash Edge

Unleash Edge is distributed as a binary and as a docker image.


  • The binary is downloadable from our Releases page.
  • We're currently building for linux x86_64, windows x86_64, darwin (OS X) x86_64 and darwin (OS X) aarch64 (M1/M2 macs)


  • The docker image gets uploaded to dockerhub and Github Package registry.
  • For dockerhub use the coordinates unleashorg/unleash-edge:<version>.
  • For Github package registry use the coordinates<version>
  • If you'd like to live on the edge (sic) you can use the tag edge. This is built from HEAD on each commit


If you have the Rust toolchain installed you can build a binary for the platform you're running by cloning this repo and running cargo build --release. This will give you an unleash-edge binary in ./target/release



Edge currently supports 2 different modes:

  • Edge - Connection to upstream node (Unleash instance or another Edge). Supports dynamic tokens, metrics and other advanced features;
  • Offline - No connection to upstream node. Full control of data and tokens;


Edge mode is the "standard" mode for Unleash Edge and the one you should default to in most cases. It connects to an upstream node, such as your Unleash instance, and uses that as the source of truth for feature toggles.

Other than connecting Edge directly to your Unleash instance, it's also possible to connect to another Edge instance (daisy chaining). You can have as many Edge nodes as you'd like between the Edge node your clients are accessing and the Unleash server, and it's also possible for multiple nodes to connect to a single upstream one. Depending on your architecture and requirements this can be a powerful feature, offering you flexibility and scalability when planning your implementation.

This means that, in order to start up, Edge mode needs to know where the upstream node is. This is done by passing the --upstream-url command line argument or setting the UPSTREAM_URL environment variable.

By default, Edge mode uses an in-memory cache to store the features it fetches from the upstream node. However, you may want to use a more persistent storage solution. For this purpose, Edge supports either Redis or a backup file, which you can configure by passing in either the --redis-url or --backup_folder command line argument, respectively. On start-up, Edge checks whether the persistent backup option is specified, in which case it uses it to populate its internal caches. This can be useful when your Unleash server is unreachable.

Edge mode also supports dynamic tokens, meaning that Edge doesn't need a token to be provided when starting up. Once we make a request to the /api/client/features endpoint using a client token Edge will validate upstream and fetch its respective features. After that, it gets added to the list of known tokens that gets periodically synced, making sure it is a valid token and its features are up-to-date.

Even though Edge supports dynamic tokens, you still have the option of providing a token through the command line argument or environment variable. This way, since Edge already knows about your token at start up, it will sync your features for that token and should be ready for your requests right away (warm up / hot start).

Front-end tokens can also be used with /api/frontend and /api/proxy endpoints, however they are not allowed to fetch features upstream. In order to use these tokens correctly and make sure they return the correct information, it's important that the features they are allowed to access are already present in that Edge node's features cache. The easiest way to ensure this is by passing in at least one client token as one of the command line arguments, ensuring it has access to the same features as the front-end token you'll be using. If you're using a frontend token that doesn't have data in the node's feature cache, you will receive an HTTP Status code: 511 Network Authentication Required along with a body of which project and environment you will need to add a client token for.

"access": {
"environment": "default",
"project": "demo-app"
"explanation": "Edge does not yet have data for this token. Please make a call against /api/client/features with a client token that has the same access as your token"

To launch in this mode, run:

$ unleash-edge edge -h
Run in edge mode

Usage: unleash-edge edge [OPTIONS] --upstream-url <UPSTREAM_URL>

-u, --upstream-url <UPSTREAM_URL>
Where is your upstream URL. Remember, this is the URL to your instance, without any trailing /api suffix [env: UPSTREAM_URL=]
-r, --redis-url <REDIS_URL>
A URL pointing to a running Redis instance. Edge will use this instance to persist feature and token data and read this back after restart. Mutually exclusive with the --backup-folder option [env: REDIS_URL=]
-b, --backup-folder <BACKUP_FOLDER>
A path to a local folder. Edge will write feature and token data to disk in this folder and read this back after restart. Mutually exclusive with the --redis-url option [env: BACKUP_FOLDER=]
-m, --metrics-interval-seconds <METRICS_INTERVAL_SECONDS>
How often should we post metrics upstream? [env: METRICS_INTERVAL_SECONDS=] [default: 60]
-f, --features-refresh-interval-seconds <FEATURES_REFRESH_INTERVAL_SECONDS>
How long between each refresh for a token [env: FEATURES_REFRESH_INTERVAL_SECONDS=] [default: 10]
-t, --tokens <TOKENS>
Get data for these client tokens at startup. Hot starts your feature cache [env: TOKENS=]
-h, --help
Print help


Offline mode should be used when you don't have a connection to an upstream node, such as your Unleash instance itself or another Edge instance. It can also be used when you need to have full control of both the data your clients will get and which tokens can be used to access it.

Since this mode does not connect to an upstream node, it needs a downloaded JSON dump of a result from a query against an Unleash server on the /api/client/features endpoint as well as a comma-separated list of tokens that should be allowed to access the server.

If your token follows the Unleash API token format [project]:[environment].<somesecret>, Edge will filter the features dump to match the project contained in the token.

If you'd rather use a simple token like secret-123, any query against /api/client/features will receive the dump passed in on the command line.

When using offline mode, you can think of these tokens as proxy client keys.

Since offline mode does not connect to an upstream node, it does not support metrics or dynamic tokens.

To launch in this mode, run:

$ ./unleash-edge offline --help
Usage: unleash-edge offline [OPTIONS]

-b, --bootstrap-file <BOOTSTRAP_FILE> [env: BOOTSTRAP_FILE=]
-t, --tokens <TOKENS> [env: TOKENS=]


Unleash edge will scale linearly with CPU. There are k6 benchmarks in the benchmark folder and we've already got some initial numbers from hey.

Do note that the number of requests Edge can handle does depend on the total size of your toggle response. That is, Edge is faster if you only have 10 toggles with 1 strategy each, than it will be with 1000 toggles with multiple strategies on each. Benchmarks here were run with data fetched from the Unleash demo instance (roughly 100kB (350 features / 200 strategies)) as well as against a small dataset of 5 features with one strategy on each.

Edge was started using docker run --cpus="<cpu>" --memory=128M -p 3063:3063 -e UPSTREAM_URL=<upstream> -e TOKENS="<client token>" unleashorg/unleash-edge:edge -w <number of cpus rounded up to closest integer> edge

Then we run hey against the proxy endpoint, evaluating toggles

Large Dataset (350 features (100kB))

$ hey -z 10s -H "Authorization: <frontend token>" http://localhost:3063/api/frontend`
CPUMemoryRPSEndpointp95Data transferred
0.16.7 Mi600/api/frontend103ms76Mi
16.7 Mi6900/api/frontend7.4ms866Mi

and against our client features endpoint.

$ hey -z 10s -H "Authorization: <client token>" http://localhost:3063/api/client/features
CPUMemory observedRPSEndpointp95Data transferred
0.111 Mi309/api/client/features199ms300 Mi
111 Mi3236/api/client/features16ms3 Gi
411 Mi12815/api/client/features4.5ms14 Gi
817 Mi23207/api/client/features2.7ms26 Gi

Small Dataset (5 features (2kB))

$ hey -z 10s -H "Authorization: <frontend token>" http://localhost:3063/api/frontend`
CPUMemoryRPSEndpointp95Data transferred
0.14.3 Mi3673/api/frontend93ms9Mi
16.7 Mi39000/api/frontend1.6ms80Mi
46.9 Mi110000/api/frontend600μs252Mi
812.5 Mi141090/api/frontend600μs324Mi

and against our client features endpoint.

$ hey -z 10s -H "Authorization: <client token>" http://localhost:3063/api/client/features
CPUMemory observedRPSEndpointp95Data transferred
0.14 Mi3298/api/client/features92ms64 Mi
14 Mi32360/api/client/features2ms527Mi
411 Mi95838/api/client/features600μs2.13 Gi
817 Mi129381/api/client/features490μs2.87 Gi

Why choose Unleash Edge over the Unleash Proxy?

Edge offers a superset of the same feature set as the Unleash Proxy and we've made sure it offers the same security and privacy features.

However, there are a few notable differences between the Unleash Proxy and Unleash Edge:

  • Unleash Edge is built to be light and fast, it handles an order of magnitude more requests per second than the Unleash Proxy can, while using two orders of magnitude less memory.
  • All your Unleash environments can be handled by a single instance, no more running multiple instances of the Unleash Proxy to handle both your development and production environments.
  • Backend SDKs can connect to Unleash Edge without turning on experimental feature flags.
  • Unleash Edge is smart enough to dynamically resolve the tokens you use to connect to it against the upstream Unleash instance. This means you don't have to worry about knowing in advance what tokens your SDKs use - if you want to swap out the Unleash token your SDK uses, this can be done without ever restarting or worrying about Unleash Edge. Unleash Edge will only collect and cache data for the environments and projects you use.


See our Contributors guide as well as our development-guide

This content was generated on