1. Home
  2. Configuration

Configuration File

The default way that Flipt is configured is with the use of a configuration file default.yml.

This file is read when Flipt starts up and configures several important properties for the server.

You can edit any of these properties to your liking, and on restart Flipt will pick up the new changes.

These defaults are commented out in default.yml to give you an idea of what they are. To change them you’ll first need to uncomment them.

These properties are as follows:


log.levelLevel at which messages are logged (trace, debug, info, warn, error, fatal, panic)info
log.grpc_levelLevel at which gRPC messages are logged (trace, debug, info, warn, error, fatal, panic)errorv1.12.0
log.fileFile to log to instead of STDOUTv0.10.0
log.encodingEncoding to use for logging (json, console)consolev1.12.0
ui.enabledEnable UI and API docstrue
cors.enabledEnable CORS supportfalsev0.7.0
cors.allowed_originsSets Access-Control-Allow-Origin header on server”*” (all domains)v0.7.0
tracing.jaeger.enabledEnable tracing support with Jaegerfalsev0.17.0
tracing.jaeger.hostThe UDP host destination to report spanslocalhostv0.17.0
tracing.jaeger.portThe UDP port destination to report spans6831v0.17.0
meta.check_for_updatesEnable check for newer versions of Flipt on startuptruev0.17.0
meta.telemetry_enabledEnable anonymous telemetry data (see Telemetry)truev1.8.0
meta.state_directoryDirectory on the host to store local state$HOME/.config/fliptv1.8.0


server.protocolhttp or httpshttpv0.8.0
server.hostThe host address on which to serve the Flipt application0.0.0.0
server.http_portThe HTTP port on which to serve the Flipt REST API and UI8080
server.https_portThe HTTPS port on which to serve the Flipt REST API and UI443v0.8.0
server.grpc_portThe port on which to serve the Flipt GRPC server9000
server.cert_filePath to the certificate file (if protocol is set to https)v0.8.0
server.cert_keyPath to the certificate key file (if protocol is set to https)v0.8.0


cache.enabledEnable caching of datafalsev1.10.0
cache.ttlTime to live for cached data60sv1.10.0
cache.backendThe backend to use for caching (options: memory, redis)memoryv1.10.0

Memory Cache

cache.memory.eviction_intervalInterval at which expired items are evicted from the in-memory cache5mv0.12.0

Redis Cache

cache.redis.hostHost to access the Redis databaselocalhostv1.10.0
cache.redis.portPort to access the Redis database6379v1.10.0
cache.redis.dbRedis database to use0v1.10.0
cache.redis.passwordPassword to access the Redis databasev1.10.0


db.urlURL to access Flipt databasefile:/var/opt/flipt/flipt.db
db.protocolProtocol (Sqlite, MySQL, Postgres, CockroachDB) for Flipt database (URL takes precedence)v0.18.0
db.hostHost to access Flipt database (URL takes precedence)v0.18.0
db.portPort to access Flipt database (URL takes precedence)v0.18.0
db.nameName of Flipt database (URL takes precedence)v0.18.0
db.userUser to access Flipt database (URL takes precedence)v0.18.0
db.passwordPassword to access Flipt database (URL takes precedence)v0.18.0
db.max_idle_connThe maximum number of connections in the idle connection pool2v0.17.0
db.max_open_connThe maximum number of open connections to the databaseunlimitedv0.17.0
db.conn_max_lifetimeSets the maximum amount of time in which a connection can be reusedunlimitedv0.17.0
db.migrations.pathWhere the Flipt database migration files are kept/etc/flipt/config/migrations


authentication.requiredEnable or disable authentication validation on requestsfalsev1.15.0
authentication.methods.token.enabledEnable static token creationfalsev1.15.0
authentication.methods.token.cleanup.intervalInterval between deletion of expired tokens1hv1.16.0
authentication.methods.token.cleanup.grace_periodHow expired a token can become before it is deleteable30mv1.16.0


From time to time configuration options will need to be deprecated and eventually removed. Deprecated configuration options will be removed after ~6 months from the time they were deprecated.

All deprecated configuration options will be removed from the documentation, however they will still work as expected until they are removed. A warning will be logged in the Flipt logs when a deprecated configuration option is used.

All deprecated options are listed in the DEPRECATIONS file in the Flipt repository as well as the CHANGELOG.

Environment Variables

All options in the configuration file can be overridden using environment variables using the syntax:

Using environment variables to override defaults is especially helpful when running with Docker as described in the Installation documentation.

Everything should be upper case, . should be replaced by _. For example, given these configuration settings:

You can override them using:


Flipt supports SQLite, Postgres, CockroachDB and MySQL databases.

SQLite is enabled by default for simplicity, however you should use Postgres, MySQL, or CockroachDB if you intend to run multiple copies of Flipt in a high availability configuration.

The database connection can be configured as follows:



The Postgres database must exist and be up and running before Flipt will be able to connect to it.


The CockroachDB database must exist and be up and running before Flipt will be able to connect to it.


The MySQL database must exist and be up and running before Flipt will be able to connect to it.


From time to time the Flipt database must be updated with new schema. To accomplish this, Flipt includes a migrate command that will run any pending database migrations for you.

If Flipt is started and there are pending migrations, you will see the following error in the console:

If it is your first run of Flipt, all migrations will automatically be run before starting the Flipt server.

You should backup your database before running flipt migrate to ensure that no data is lost if an error occurs during migration.

If running Flipt via Docker, you can run the migrations in a separate container before starting Flipt by running:


Flipt supports importing and exporting your feature flag data since v0.13.0.


To import previously exported Flipt data, use the flipt import command. You can import either from a file or from STDIN.

To import from STDIN, Flipt requires the --stdin flag:

If not importing using --stdin, Flipt requires the file to be imported as an argument:

This command supports the --drop flag that will drop all of the data in your Flipt database tables before importing. This is to ensure that no data collisions occur during the import.

Be careful when using the --drop flag as it will immediately drop all of your data and there is no undo. It is recommend to first backup you database before running this command just to be safe.


To export Flipt data, use the flipt export command.

By default, export will output to STDOUT:

You can also export to a file using the -o filename or --output filename flags:


Flipt supports both in-memory cache as well as Redis to enable faster reads and evaluations. Enabling caching has been shown to speed up read performance by several orders of magnitude.

Enabling in-memory caching when running more than one instance of Flipt is not advised as it may lead to unpredictable results. It is recommened to use Redis instead if you are running more than one instance of Flipt.

Caching works as follows:

  • All flag reads and evaluation requests go through the cache
  • Flag cache entries are purged whenever a write to a flag or it’s variants occur or the TTL expires
  • Evaluation cache entries are purged after the TTL expires only
  • A cache miss will fetch the item from the database and add the item to the cache for the next read
  • A cache hit will simply return the item from the cache, not interacting with the database

See the Cache section for how to configure caching.


You can also configure an optional duration at which items in the cache are marked as expired.

For example, if you set the cache TTL to 5m, items that have been in the cache for longer than 5 minutes will be marked as expired, meaning the next read for that item will hit the database.

Setting an eviction interval (in-memory cache only) will automatically remove expired items from your cache at a defined period.

The combination of cache expiration and eviction can help lessen the amount of memory your cache uses, as infrequently accessed items will be removed over time.

To tune the expiration and eviction interval of the cache set the following in your config:


Flipt developers rely on anonymous usage data to help prioritize new features and improve the product. The information collected is completely anonymous, never shared with external entities, and you can opt out at any time.

What Kind of Data is Collected?

  • Flipt version

You can view the full schema of the telemetry data on GitHub.

We use Segment to collect the data. Only the creator of Flipt has access to the data.

How to Disable Telemetry

There are multiple ways in which you can disable telemetry collection:

Configuration File

Environment Variable


Flipt exposes Prometheus metrics at the /metrics HTTP endpoint. To see which metrics are currently supported, point your browser to FLIPT_HOST/metrics (ex: localhost:8080/metrics).

You should see a bunch of metrics being recorded such as:

There is an example provided in the GitHub repository showing how to setup Flipt with Prometheus.


Flipt supports distributed tracing via the OpenTracing protocol and Jaeger library. Enable tracing via the configuration values described above and point Flipt to your Jaeger host to record spans.

There is an example provided in the GitHub repository showing how to setup Flipt with Jaeger.


Once authentication has been set to required: true all API routes will require a client token be presented.

Browser sessions (UI) will require a session compatible authentication method be enabled.

Session compatible authentication methods are not yet supported, meaning that authentication renders the UI unusable and Flipt is purely API driven.

Implementation of this feature is in the pipeline and scheduled for an upcoming release.

Flipt supports the ability to secure its core API routes by setting the required field to true on the authentication configuration object. Once enabled, all API routes will require a client token be presented in-order to authenticate the request.

When authentication is set to required, the API will ensure valid credentials are present on all API requests.

See the Authentication documentation for more details on Flipt’s API authentication handling.

Authentication Methods

Beneath the authentication section of the configuration file is the methods section. Each key beneath this section is a particular authentication method. These methods are disabled (enabled: false) by default. Enabling and configuring a method allows for different ways to establish client token credentials within Flipt.


Each authentication method contains a nested cleanup configuration object. This object configures the periodic deletion of expired authentications created with the associated method.

The cleanup object currently contains two keys interval and grace_period. The interval is used to configured how frequently a delete expired tokens is performed. Whereas, grace_period is used to ensure that expired tokens are preserved for at-least this configured duration.

This allows you to keep authentications around for auditing purposes after expiration. Expired tokens are instances where the expires_at timestamp occurs before the current time. The grace period is added onto this timestamp as a predicated, when the delete operation is made.

Tokens, when presented as a credential to the API, which have expired (expires_at is before now()) will begin immediately failing authentication. The grace_period is simply for the cleanup process.


This core and first method within Flipt is known as token. The token method provides the ability to create client tokens statically, with optional expiry constraints.


It is possible to secure Flipt simply by running it behind a reverse-proxy in your own trusted environment. An example of this can be found in the core Flipt repository here.


Currently, Flipt only supports authentication without any extended authorization capabilities. Authorization is something we’re actively exploring and we will update this section as we settle on a design.

We would appreciate your input into designing authorization. Head over to our discord and let us know what you need from Flipt.