Unleash: self-hosted feature flags under AGPL-3.0

The problem Unleash solves, and who ends up running it

Shipping a feature is usually coupled to deploying code. Unleash breaks that coupling by keeping flag definitions and activation strategies in a central server that your application queries at runtime, so a flag can be turned on for a subset of users without a new build. The README frames the benefit as testing code with real production data and letting several features be developed at once without separate feature branches.

The audience is narrower than the tagline suggests. Because the open-source distribution is a server you host, the people who get value from it are platform or backend teams that already run Postgres and are comfortable owning another stateful service. A single developer wanting a boolean in a side project pays a real cost here: a container, a database, and token management. Unleash also offers a hosted Enterprise trial, and the README positions that path separately from the local open-source setup, which is a fair signal about where the operational burden sits.

How flag evaluation actually flows

The server is the source of truth. According to the repository layout, the backend lives under src/ and the admin UI under frontend/, both shipped in one Docker image that exposes port 4242. The docker-compose.yml defines two services: web, running unleashorg/unleash-server:latest, and db, running postgres:15 with a database named db. The web service receives DATABASE_URL and DATABASE_SSL as environment variables and waits for the database healthcheck before starting.

Tokens are seeded at boot. The compose file sets INIT_FRONTEND_API_TOKENS and INIT_BACKEND_API_TOKENS, which is why a fresh instance already has working credentials. The README splits SDKs into two families and gives different endpoints for each: frontend SDKs use http://localhost:4242/api/frontend/ with a clientKey, while backend SDKs use http://localhost:4242/api/ with an API token. That split matters. A frontend key is meant to be embedded in a browser bundle, so it can only read flags for the environment it was issued for; a backend token has broader reach and should never ship to a client.

Evaluation itself is a function call in your code. The README's Java example is the shape all SDKs follow: call isEnabled with the flag name and branch on the boolean. The README states there are 15 official client and server SDKs plus more than 15 community SDKs, and the topic list includes activation-strategies and variants, so targeting rules and multi-variant flags are part of the model rather than something you build on top.

Running Unleash locally with Docker and checking your first flag

The README requires git and docker, then gives three commands. The compose file itself carries a warning that it is for demo, development and learning only and that Unleash takes no responsibility for data leaks arising from it, so treat this as an evaluation setup and nothing more.

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

After the containers report healthy, open localhost:4242 in a browser and log in with the credentials the README lists: username admin, password unleash4all. You should land in the admin UI where flags are created and strategies assigned.

Next, wire an SDK to the instance. If you are using the compose setup, the README gives these values verbatim: for frontend SDKs the URL is http://localhost:4242/api/frontend/ and the clientKey is default:development.unleash-insecure-frontend-api-token. For backend SDKs the API URL is http://localhost:4242/api/ and the token is default:development.unleash-insecure-api-token. Both names contain the word insecure for a reason: the compose file comments say the default API token should not be used in production.

if (unleash.isEnabled("AwesomeFeature")) {
  // do new, flashy thing
} else {
  // do old, boring stuff
}

That Java snippet is the README's own example, and the syntax differs per language, but the contract is the same everywhere: one call returning a boolean. If you would rather not clone anything, the README points at a live demo instance with no signup and at a 14-day Enterprise cloud trial. If you want to run from source instead of Docker, the README defers to the contributing guide rather than repeating the steps, and package.json requires Node 22 or newer with pnpm scripts such as dev:backend and dev:frontend.

Where Unleash is the wrong tool

The compose file is the clearest limitation, and it is stated by the project rather than inferred. It disables database SSL, sets POSTGRES_HOST_AUTH_METHOD to trust so connections are accepted blindly, and ships two well-known tokens. None of that is a production posture, and the file says so twice. A production deployment means supplying your own Postgres, your own credentials and your own TLS configuration, which the README routes to the self-hosting and configuration documentation instead of covering inline.

The second limitation is operational. Flag state now lives in a database you own, so its availability becomes part of your application's startup path. The README does not document backup, restore, migration or rollback procedures for the open-source server, and the repository's test-migrations directory suggests migrations are tested in CI rather than described for operators. If your team has no one to own a Postgres instance and its upgrades, a hosted service removes that work entirely.

A third case is licensing. The package is AGPL-3.0-or-later. For an internal service that only calls the API, that is usually a non-issue, but if you plan to modify the server and offer it to third parties over a network, the licence terms deserve a lawyer's reading rather than a blog post's. That is a boundary, not legal advice.

Unleash compared with LaunchDarkly

The comparison people actually search for is Unleash versus LaunchDarkly, and the difference is deployment model, not feature lists. LaunchDarkly is a hosted service: you sign up, get an SDK key, and the vendor runs the flag store, the evaluation infrastructure and the uptime. Unleash's open-source path inverts that. You run the server and the Postgres database, and in exchange the flag data and the evaluation path stay inside your network, which matters for teams with data residency constraints or an internal rule against third-party runtime dependencies.

The trade is explicit. Self-hosting gives you control over where flag state lives and removes a per-seat or per-request vendor bill, but you inherit upgrades, backups and capacity planning. The README does not document a migration path between the two products, so switching later is not a one-command operation on either side. If your main reason for wanting Unleash is cost, price the operational time honestly against the vendor bill before deciding.

Maintenance, releases and what the licence means for upgrades

The repository is not archived, and the last push was on 2026-09-21. Releases are frequent and date-stamped: v8.2.0 on 2026-09-08, v8.1.0 on 2026-08-05, and v8.0.3 on 2026-07-10. The package version in package.json matches the newest tag at 8.2.0, and the repository includes cliff.toml, which is a changelog generator config, so release notes are produced from commit history rather than hand-written. That is a reasonable signal for upgrade planning, but the README does not document a rollback procedure, and the compose file pins the image to latest, which will silently move you forward on every pull. Pin a specific tag in your own compose file instead.

On licensing, AGPL-3.0-or-later is a copyleft licence with a network clause. Running an unmodified server for your own applications is the ordinary case. Modifying the server and exposing it to users over a network is where obligations can attach, and the repository carries a CLA.md for contributors, which is about contribution terms rather than your usage rights. Read the LICENSE file in the repository and get proper advice if your distribution model is unusual. The README does not discuss licence implications for embedding the server in a commercial product.

Editorial conclusion

Adopt Unleash if you want flag state inside your own network and can operate a Postgres-backed Node service; the docker compose file in the repository is enough to evaluate it today. Do not adopt it if you need a managed control plane with no database to run, or if AGPL-3.0-or-later terms conflict with how you distribute your product. Before rolling it out, verify which SDK version your language needs, confirm the API token scopes you will issue per environment, and read the self-hosting configuration page because the README does not document backup, upgrade or rollback procedures.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. Unleash/unleash on GitHub