Unleash: What Feature Flags Are and How to Turn Them On

⏱️ Reading time: 12 min

Unleash lets you turn a feature on or off in production without touching the code or waiting for a new deployment, and it is, according to its own repository, the most widely adopted open source feature flags platform on GitHub.

📑 En este artículo

1. TL;DR
2. What are feature flags?
3. Why feature flags matter
4. How Unleash works under the hood
5. Practical examples with Unleash SDKs
6. Getting started with Unleash locally
7. Real use cases for feature flags
8. Common mistakes and best practices
9. Comparison: Unleash versus other ways to manage feature flags
10. Going deeper: advanced activation strategies
11. Frequently Asked Questions
    1. What is Unleash?
    2. How do feature flags work in Unleash?
    3. Is Unleash free?
    4. What sets Unleash apart from a closed platform like LaunchDarkly?
    5. Do I need Docker to use Unleash?
12. References

The project offers 15 official SDKs and more than 15 community-maintained ones, covering almost any backend or frontend language. For a team that deploys several times a day, separating the code release from the feature activation is the difference between a bug that hits every user at once and one that only reaches 1% of them.

TL;DR

• Unleash separates the deployment of code from the activation of a feature through a flag evaluated at runtime.
• A full local setup runs with docker compose up -d and is ready at localhost:4242.
• Activation strategies, such as percentage, user list, or variant, decide who sees the feature without touching the client code.
• More than 30 official SDKs cover Java, Node.js, Python, Go, .NET, and more, with the same isEnabled() call in each one.
• Teams with audit requirements get role-based access control, change requests, and SSO in the Enterprise editions.

What are feature flags?

Feature flags are configuration switches that turn a feature on or off at runtime, without modifying or redeploying the source code. They let you roll out a feature to a percentage of users and revert it instantly if it fails, without relying on a full rollback.

The simplest analogy is a light switch with several circuits: you turn one off without cutting power to the whole house. Something similar happens in software. The new feature’s code is already in production, but the flag decides whether it runs for a particular user. A feature flag isn’t just a boolean stored in a database; it’s the point where the business decides who sees what, without waiting for the next deployment cycle.

Not every configuration switch is a feature flag. An environment variable that sets the server port doesn’t change on the fly and doesn’t depend on who makes the request. A feature flag does, and it also needs an interface where a product team can turn it on or off without asking anyone for a deploy. That’s exactly what Unleash solves: a central server with an API and admin dashboard, plus SDKs that evaluate the flag inside each client application.

Why feature flags matter

The main reason is to separate two events that for decades were one and the same: deploying code and activating it for users. When both steps are tied together, any bug in a new feature shows up as soon as the deploy finishes, and reverting it means another full deploy. With feature flags, the code can live in production, turned off, for days before anyone sees it.

This enables development on a single main branch, even with half-finished features, because the flag keeps them hidden until they’re ready. It also enables the emergency switch: if a new feature degrades the service, turning it off takes the time of a click in the dashboard, not the time of an infrastructure rollback.

The third reason is segmentation. An activation strategy can show the feature only to internal users, to a list of beta customers, or to a growing percentage of traffic. That turns every launch into a controlled experiment instead of an all-or-nothing bet against the entire user base.

How Unleash works under the hood

The architecture has three parts: a central API with its database, a web admin dashboard, and the SDKs that run inside each client application. The SDK doesn’t query the API on every request: it downloads the full flag configuration on startup and refreshes it in the background every few seconds, so evaluating a flag is an in-memory operation, not a network call per user.

flowchart TD
    A["Client app"] --> B["Unleash SDK"]
    B --> C["Unleash API"]
    C --> D[("Database")]
    C --> E["Admin UI"]
    subgraph Server
    C
    D
    E
    end

That separation is why evaluating a flag takes microseconds: the decision of whether it’s active for that user already lives in the process memory. The cost is paid by the Unleash server, which keeps all connected SDKs in sync; in Unleash Open Source that synchronization runs on a single Postgres database.

Each flag belongs to a project and lives in one or more environments (development, staging, production), so you can activate a feature in staging without production seeing it. Within each environment, one or more strategies decide the “who”: all users, a fixed percentage, a list of specific IDs, or a combination of constraints like country or app version.

There’s also a trust difference between the two types of SDK. A backend SDK runs on a server nobody else controls, so its token can see the full configuration of every flag. A frontend SDK runs in the user’s browser, where anyone can read the page’s source code, which is why it uses a different URL (/api/frontend/) and a different token, designed to be exposed without leaking flag configuration that doesn’t belong to that client.

sequenceDiagram
    participant App as Application
    participant SDK as Unleash SDK
    participant API as Unleash API
    App->>SDK: isEnabled("new-checkout")
    SDK->>API: syncs configuration every few seconds
    API-->>SDK: list of flags and strategies
    SDK-->>App: true or false depending on the strategy
    Note over App,SDK: evaluation is local, no call per request

Practical examples with Unleash SDKs

The simplest example, taken from the Unleash repository itself, is a conditional call in Java:

if (unleash.isEnabled("new-checkout")) {
    renderCheckoutV2();
} else {
    renderCheckoutV1();
}

What it does: it evaluates whether the new-checkout flag is active for the current user according to the strategy configured in the dashboard. If it is, it runs the new path; if not, the usual one. The output isn’t an HTTP response, it’s a boolean that decides which code branch that specific request runs.

In Node.js, the typical pattern is to initialize the client once when the service starts and wait for it to sync before evaluating anything:

const { initialize } = require('unleash-client');

const unleash = initialize({
  url: 'http://localhost:4242/api/',
  appName: 'checkout-service',
  customHeaders: { Authorization: 'default:development.unleash-insecure-api-token' }
});

unleash.on('synchronized', () => {
  console.log(unleash.isEnabled('new-checkout'));
});

What it does: it downloads the flag configuration from the local API and, once synced, evaluates new-checkout without asking the network for anything: the SDK keeps the configuration in memory and refreshes it in the background. The expected output of console.log is true or false, never a pending promise or an error, because the evaluation is purely local.

Getting started with Unleash locally

You need Git and Docker with Docker Compose included. On Windows, Docker Desktop needs the WSL2 backend enabled; on macOS, installing Docker Desktop is enough; on Linux you can use the Docker daemon directly, without Desktop.

With both installed, the commands are identical on all three platforms:

git clone [email protected]:Unleash/unleash.git
cd unleash
docker compose up -d

That command downloads the images and spins up the API, the Postgres database, and the admin dashboard. Once it’s done, open http://localhost:4242 in your browser and log in with username admin and password unleash4all: these are the development credentials that ship in the repository’s docker-compose.yml.

⚠️ Heads up: admin/unleash4all is the official docker-compose’s development credential. Change it before exposing the instance beyond your local machine.

To connect a frontend SDK to this instance, the URL is http://localhost:4242/api/frontend/ and the clientKey is default:development.unleash-insecure-frontend-api-token. For a backend SDK, the base URL is http://localhost:4242/api/ with the token default:development.unleash-insecure-api-token. Both tokens are for development, and the token’s own name makes that explicit with the word “insecure”.

To confirm a flag is active without relying on code, just open the admin dashboard, go into the project, and look at the flag’s toggle in the corresponding environment: if it’s green, any SDK connected to that environment will evaluate it as true as soon as it syncs. There’s no one-line command that confirms it from outside without going through that screen or the SDK itself.

Real use cases for feature flags

The most common one is the gradual rollout: activate a new feature for a small percentage of users, watch the error metrics for a while, and raise the percentage only if everything stays stable. If something breaks, you go back to zero without any deploy.

The second is the closed beta program: a user-list strategy shows the feature only to the IDs on a specific list, without touching anything else in the behavior for everyone else.

The third is the emergency switch for external integrations. If a payment or shipping provider starts failing, turning off the flag that calls that integration keeps the problem from spreading to the rest of the application, instead of waiting for a hotfix.

The fourth is the controlled experiment: Unleash lets you define variants within the same flag, so that one portion of traffic sees version A and another portion sees version B, and each SDK reports which variant each user got so you can compare metrics afterward.

Common mistakes and best practices

• Zombie flags: a flag that’s been at 100% for months and nobody removed from the code. Every flag should have an expiration date and a task to clean it up.
• Cross-dependencies between flags: if flag B only makes sense when A is active, that relationship needs to be documented, because Unleash doesn’t infer it on its own.
• Not testing both branches: it’s common to test only the path with the flag active and assume the old code still works the same as before.
• Backend tokens on the client: the token with access to the full API should never reach a browser; that’s what the frontend token is for, with scoped-down permissions.
• Strategies without stable assignment: a gradual percentage rollout without a stable criterion, like the user ID, can show the feature to the same person sometimes and not others, which breaks the experience.

Comparison: Unleash versus other ways to manage feature flags

Going deeper: advanced activation strategies

The most common strategy in production is a gradual rollout with stable per-user assignment (stickiness): Unleash computes a hash from the user ID and the flag name, so the same person always lands on the same side of the percentage as long as that percentage doesn’t change. Without that consistency, each evaluation would be almost a different coin flip for the same user.

stateDiagram-v2
    [*] --> Disabled
    Disabled --> PartialRollout: activate by percentage
    PartialRollout --> Active: raise to 100 percent
    PartialRollout --> Disabled: revert
    Active --> Disabled: turn off the flag

Constraints add extra conditions on top of that strategy: country, app version, customer type, or any field from the context the SDK sends. You can combine several constraints with a percentage strategy, so that, for example, the gradual rollout only applies to users in a specific country.

For larger teams, the real difference between the Open Source and Enterprise editions isn’t in the SDK or the flag evaluation, that’s identical, but in the processes around it: according to the official repository, Enterprise adds role-based access control, change requests, single sign-on, and SCIM for automatic user provisioning, designed for organizations where a flag change in production needs approval before it applies.

Your next step: clone the repository, run docker compose up -d, create your own flag called my-first-test in the dashboard at localhost:4242, and read it from your language’s SDK using the same logic as the isEnabled() example.

Frequently Asked Questions

What is Unleash?

Unleash is an open source platform for managing feature flags: it exposes a central API, a web admin dashboard, and official SDKs to connect backend and frontend applications.

How do feature flags work in Unleash?

Each SDK downloads the flag configuration on startup and refreshes it in the background. Evaluating a flag within the code is an in-memory operation that checks that local configuration, not a network call on every check.

Is Unleash free?

The Open Source edition can be self-hosted at no license cost. The Enterprise edition, with role-based access control, SSO, and SCIM, is a commercial plan that, according to its repository, offers a 14-day free trial.

What sets Unleash apart from a closed platform like LaunchDarkly?

Unleash has an open source edition that can be installed and run on your own infrastructure at no license cost. A closed platform managed by a vendor doesn’t offer that free self-hosting option, in exchange for not having to operate the server.

Do I need Docker to use Unleash?

To try it locally, it’s recommended, because docker compose up -d spins up the API, the database, and the dashboard in a single step. In production, it can also be installed from source with Node.js following the repository’s contribution guide, or you can use Unleash Enterprise’s cloud without installing anything yourself.

References

• Unleash on GitHub: the project’s official repository, with installation instructions and the listed SDKs.
• Official Unleash documentation: configuration guides, activation strategies, and API reference.
• Official Unleash website: information about the Enterprise edition and the free trial.
• Feature Toggles, by Pete Hodgson: the reference article on the feature flags pattern in software development.

📱 Like this content? Follow @programacion on Telegram for daily tech content in Spanish: quick summaries, fresh content every day. @programacion

Featured image: Foto de Pankaj Patel en Unsplash