Configure Enterprise Edge

If you are using Unleash Enterprise Edge hosted, these configurations are managed for you automatically. You do not need to set environment variables or manage tokens via CLI.

This reference covers all configuration options for Enterprise Edge self-hosted.

Configure the operating mode

Edge supports two modes: Edge mode (default) and Offline mode.

Edge mode

Connects to Unleash and synchronizes feature flags. Use for production deployments.

$
unleash-edge edge --upstream-url https://your-unleash.com --tokens your-token

Offline mode

Serves flags from a local file without upstream connection. Use for development, testing, or air-gapped environments. See Offline mode configuration for all available options.

$
unleash-edge offline \
>
  --bootstrap-file /path/to/features.json \
>
  --client-tokens your-token

In offline mode, Edge validates requests against tokens you provide at startup rather than validating with Unleash. Use --client-tokens for backend SDK access and --frontend-tokens for frontend SDK access. These tokens don’t need to exist in Unleash—they serve as shared secrets between your SDKs and Edge.

To use offline mode, you also need to provide a local file that contains your feature flag configurations. You can create one by exporting your feature flags from Unleash:

$
curl -H "Authorization: your-token" \
>
  https://your-unleash.com/api/client/features > features.json

Alternatively, use a simplified JSON for development:

1
{
2
  "my-feature": { "enabled": true },
3
  "another-feature": { "enabled": false, "variant": "control" }
4
}

When using offline mode you must specify one or more tokens at startup. These tokens let your SDKs access Edge. Tokens following the Unleash API format [project]:[environment].<somesecret> allow Edge to recognize the project and environment specified in the token, returning only the relevant features to the calling SDK. On the other hand, for tokens not adhering to this format, Edge will return all features if there is an exact match with any of the startup tokens. Edge does not support multiple environments in offline mode. All tokens added at startup will receive the same list of features passed in as the bootstrap argument.

Configuration reference

Global configuration

These settings apply to the Unleash Edge process regardless of whether it is running in Edge or Offline mode.

Server and network

Security

Access control and proxy

Logging and debugging

Edge mode configuration

These settings apply when running Unleash Edge in Edge mode.

Upstream connection

Synchronization and polling

Persistence

Observability

OpenTelemetry exporting

Unleash Enterprise Edge allows you to export tracing and logs to an OpenTelemetry Protocol (OTLP) compatible collector.

If OTEL_EXPORTER_OTLP_ENDPOINT is not set, Edge logs to stdout using RUST_LOG settings and the LOG_FORMAT setting (json, pretty, or plain).

GRPC exporter

To export to an OTLP/GRPC compatible collector:

$
# Default GRPC collector listens on port 4317
$
unleash-edge edge \
>
  --otel-exporter-otlp-endpoint http://localhost:4317 \
>
  --upstream-url https://your-unleash.com \
>
  --tokens your-token

HTTP exporter

Edge supports HTTP/JSON for OTLP export. HTTP/Protobuf is not supported.

To export to an HTTP/JSON compatible collector:

$
# Default HTTP collector listens on port 4318
$
unleash-edge edge \
>
  --otel-exporter-otlp-endpoint http://localhost:4318 \
>
  --otel-exporter-otlp-protocol http \
>
  --upstream-url https://your-unleash.com \
>
  --tokens your-token

Custom headers

You can add custom headers to OTLP requests using standard OpenTelemetry environment variables. Headers use W3C Baggage format.

Upstream mTLS

Offline mode configuration

These settings apply when running Unleash Edge in Offline mode.

Debugging

View internal state

Health check

$
unleash-edge health [OPTIONS]
$
$
Options:
$
  -e, --edge-url <URL>   Edge URL [default: http://localhost:3063]
$
  -c, --ca-certificate-file <FILE>   CA cert for self-signed TLS

Ready check

$
unleash-edge ready [OPTIONS]
$
$
Options:
$
  -e, --edge-url <URL>   Edge URL [default: http://localhost:3063]
$
  -c, --ca-certificate-file <FILE>   CA cert for self-signed TLS