Migrate from ConfigCat to Unleash

A planned move from ConfigCat to self-hosted Unleash, covering what maps cleanly, what needs rework, and how to run both systems in parallel before cutover.

On this page

Migrate from ConfigCat to Unleash: what the move involves

Moving from ConfigCat to Unleash is an export, mapping and SDK-swap project that should run in parallel with ConfigCat until every flag has been verified. You are probably here because of a renewal, a change in download-based pricing, a data residency requirement, or a wish to keep flag evaluation inside your own network. The work is not a single import: you read products, configs, environments and targeting rules out of ConfigCat, recreate them in Unleash, replace the SDKs in each application, and then cut over one service at a time. Platform engineering or application teams usually do the work, often with an implementation partner such as DeployOpen that plans the scope in writing before any changes begin. Costs fall into one-time items (export scripts, mapping decisions, SDK changes, testing and cutover) and recurring items (hosting Unleash, PostgreSQL, backups, upgrades and support). Ask any partner to price the mapping of your specific targeting rules, not a generic flag count, because that is where the effort varies most. The effort and risk are moderate for a small flag estate and rise with the number of environments, segments and percentage rollouts. Two design constraints matter early: Unleash Open Source is limited to 1 project and 2 environments, so most multi-team setups will need an Enterprise plan or a different project layout, and the open-source version of Unleash Edge reaches end of life on December 31, 2026, so confirm your caching design before you depend on it. Also plan for users who are re-bucketed during partial rollouts, since changing the hashing or rollout key can move users between variants, and agree how you will handle that before the cutover.

Which ConfigCat capabilities map to Unleash, and where the gaps are

This table maps each ConfigCat capability in a migration to its closest Unleash equivalent and marks it clean, needs rework or gap. Clean rows can be recreated directly, rework rows change shape during the move, and gap rows can block the plan under Unleash Open Source limits. Read the gap rows first, because the one-project and two-environment limit decides whether the free edition fits your setup.

ConfigCat capabilityUnleash equivalentStatus and what to confirm
On/off feature flagsFeature toggles with an enabled state per environmentClean. Confirm the Unleash SDK for your language supports the flag types you use.
Percentage optionsGradual or flexible rollout strategy with a stickiness settingNeeds rework. Users may be re-bucketed in partial rollouts, so confirm stickiness and test before cutover.
Targeting rulesActivation strategies with constraints on context fieldsNeeds rework. Rewrite each rule by hand and confirm operators and context field names match your app.
SegmentsSegments referenced by strategiesNeeds rework. Import and export carry segments as references only, so create them in the target first and confirm availability on your tier.
EnvironmentsEnvironments within a projectGap. Unleash Open Source allows 2 environments per instance; count the environments you run before choosing a tier.
ProductsProjectsGap. Unleash Open Source allows 1 project; products that span several apps need consolidation or a paid tier.
Remote config JSON valuesVariants with payloadsNeeds rework. Confirm how the SDK reads the JSON payload and test each config value against the ConfigCat output.
Flag volume and change historyFeature flags counted per instance; audit data kept in UnleashNeeds rework. Open Source lists 5,000 flags per instance; count flags first and export ConfigCat audit history separately before its retention window closes.

What data moves through the Public Management API and what you rebuild

ConfigCat's Public Management API can read most of the configuration you need, but the export is only half the job. Each object lands in Unleash differently, and some pieces must be created by hand before any import will succeed. The cards below separate what you can pull out, what Unleash needs in place first, and the integrations that stop working at cutover.

Products, configs and environments

Products map loosely to Unleash projects, and ConfigCat configs and environments determine how many flag sets you carry over. Read each product's configs and environments through the Public Management API and record the count before you plan the target. Unleash Open Source allows 1 project and 2 environments, so a ConfigCat setup with several products or stages needs an Enterprise plan or a consolidation decision before import. Confirm the limit with Unleash before you commit.

Flags and targeting rules

Flags, their default values, and targeting rules are the core payload to export. ConfigCat targeting rules, percentage options and segment conditions need translating into Unleash activation strategies, and this translation is manual for anything beyond simple cases. Export each rule as JSON, then write a mapping table that shows the ConfigCat condition, the Unleash strategy and any loss of precision. Treat this table as the sign-off artifact for product owners.

Segments and custom strategies

Unleash import and export moves feature flag configurations as JSON, but segments and custom strategies travel only as references. The target must already contain every segment and custom strategy a flag points to, or the import fails for those flags. Create segments in Unleash first, using the same names and conditions you exported from ConfigCat, then run a test import into a non-production instance. Record any segment that did not match exactly.

Remote config values and JSON payloads

ConfigCat configs can carry non-boolean values such as strings, numbers and JSON, and teams often use them for runtime settings rather than release toggles. Unleash models these through variants on flags, so each value needs a variant with a matching payload and a clear default. Check every consumer that reads a remote config value, because type changes or renamed keys break applications silently. Keep a single inventory of these keys before cutover.

SDKs, webhooks and CI jobs

Application SDKs are replaced at code level, since ConfigCat SDK calls must move to Unleash SDKs or an OpenFeature provider. Webhooks that notify Slack, incident tools or deployment pipelines need new endpoints in Unleash, and any CI job that edits flags through the ConfigCat API needs a rewrite against the Unleash Admin API. Inventory every caller in your repositories and pipelines, since these integrations rarely appear in flag documentation.

Audit trail and access records

ConfigCat keeps an audit log within its own retention window, and that history does not move with the flags. Export the audit entries you need for change management or evidence before the plan ends, and store them in your own archive. In Unleash, rebuild user access, roles and approval steps, and confirm which roles your Open Source or Enterprise edition provides. Ask your compliance lead which records must survive the cutover.

The migration sequence from inventory to decommission

This sequence moves ConfigCat flags into Unleash in six stages, and each stage closes with a named output that must be complete before the next begins. Keeping every change small and reviewable limits the risk of mismatched evaluations and re-bucketed users.

  1. Inventory products, configs and flags

    Start by listing every ConfigCat product, config, environment and flag, along with its targeting rules, percentage options and any remote config values. Read these through the Public Management API, and record how you will handle rate limits during the read. Assign an owner to each flag, because a flag with no owner or no recent evaluation needs a decision before it moves. The step is done when every flag in scope appears once in the inventory list, with its environment and its consuming services named and signed off by the platform team and the feature owners.

  2. Build the mapping sheet for Unleash

    Map each ConfigCat concept to its Unleash equivalent. Targeting rules become activation strategies, percentage options become rollout strategies on a chosen stickiness field, and user attributes that drive audiences become Unleash segments. Remote config values have no direct one-to-one match, so decide whether each one becomes a variant or moves to application configuration. Unleash Open Source allows 1 project and 2 environments, so decide early whether your design needs an Enterprise plan. The step is done when the mapping sheet has one row per flag, a target strategy, and a named owner for each open question.

  3. Pilot one low-risk flag set

    Choose a small set of flags with limited user impact, such as a UI label or an internal banner, and recreate them in a non-production Unleash environment. Create any segments or custom strategies first, because Unleash exports reference them and they must exist in the target before import. Import the definitions through the import feature or the Admin API, then switch the SDK in one non-production service and compare evaluations with ConfigCat for the same test users. The step is done when the pilot report lists each flag, the matching and mismatching results, and the fixes applied.

  4. Run both systems in parallel

    Place both providers behind an abstraction layer, such as the OpenFeature SDK with a provider for each system, so application code does not change at cutover. Keep ConfigCat serving production while Unleash receives the same definitions and is evaluated in shadow for selected services. Log every change made in either system so the two definitions do not drift apart. For partial rollouts, users may be re-bucketed if the hashing key or rollout definition differs, so compare bucket assignments for a sample of users before any user-facing switch. The step is done when the parallel-run log shows that flag values agree across both systems.

  5. Cut over one environment at a time

    Move environments in order of risk, starting with development, then staging, and leaving production last. For each environment, freeze ConfigCat edits, re-export the final definitions, import them into Unleash, switch the SDK provider, and confirm evaluations in the Unleash admin UI. Tell the affected product owners before the switch if partial rollouts will re-bucket users. If you plan to use Unleash Edge for scale, note that the open-source version reaches end of life on December 31, 2026, and Unleash recommends that open-source Edge users move to an Enterprise plan. The step is done when the cutover checklist is signed for each environment and a rollback path to ConfigCat is documented.

  6. Decommission ConfigCat and archive the record

    After every environment has run on Unleash for a period your change board agrees, revoke ConfigCat SDK keys, remove the ConfigCat provider from code, and disable the Public Management API tokens. Before the subscription ends, export the audit log within its retention window. Store the inventory, mapping sheet, pilot report, parallel-run log and cutover checklists in an archive your compliance team controls. Ask ConfigCat to confirm in writing how your data is handled at termination. The step is done when the retention archive and a decommission record show that no service still calls ConfigCat.

Handling users who are re-bucketed in partial rollouts

A percentage rollout only keeps a user in the same variant if the bucketing inputs stay the same. Both ConfigCat and Unleash decide a user's bucket by hashing an identifier, usually the user ID, together with a seed or a flag-specific salt. If Unleash hashes a different attribute, uses a different group ID, or derives its rollout from a different seed than ConfigCat did, a user who was in the 30 percent treatment in ConfigCat can land in the control group after cutover. That is re-bucketing, and it is invisible in the code but very visible in metrics and in support tickets. Before you copy any percentage, confirm with ConfigCat which attribute it hashes for each percentage rule and whether a rule's percentage option uses a salt you can reproduce. Then confirm the same for Unleash's gradualRolloutUserId or flexibleRollout strategy and its groupId setting. Ask both vendors in writing, because the answer determines the stickiness key you configure.

Choose the stickiness key that matches what ConfigCat actually hashes, and do not assume the user ID is the right choice just because it is common. Where the vendor confirms the basis, set the same key in Unleash and set a stable groupId per flag so the bucket is not tied to the flag name if you later rename it. Then test before any traffic moves. Take a sample of real user IDs, record the variant each one receives from ConfigCat's SDK, and evaluate the same IDs against a non-production Unleash environment using the same rollout percentage. Count mismatches, and do not proceed until the mismatch rate is zero for the sample, or until you understand every difference. Treat a sample as illustrative only: its size should reflect your user base, and the decision belongs to your team.

Align or freeze percentages before cutover. Pause changes to rollout percentages in ConfigCat for the flags in scope and record their current values in your export, so the Unleash configuration reflects a known state rather than a moving target. Mirror the percentage exactly, including any rule ordering, because a user who matches an earlier targeting rule is not bucketed by a later percentage. Expect some re-bucketing to be unavoidable if the hashing cannot be matched, and plan for it: announce it internally, avoid moving flags with active experiments, and prefer moving rollouts that are at 0 or 100 percent first. Keep the ConfigCat flag running as the source of truth until your comparison is clean, and record the cutover date and the percentages used in your change log.

What drives cost and duration, and how to keep each down

This table lists the factors that change the effort and recurring cost of moving from ConfigCat to self-hosted Unleash, and what each one means in practice. Read it before scoping, because the largest swings usually come from how many products, environments and services are involved, and from whether Unleash Open Source limits force a paid plan. The main takeaway is that the one-time migration work and the recurring hosting and staffing costs should be quoted separately.

DriverWhy it changes cost or effortHow to keep it down
Products and environmentsEach ConfigCat product and environment must be recreated, and Unleash Open Source allows only 1 project and 2 environments per the Unleash pricing page.Inventory every product and environment first, retire unused ones, and decide early whether the target needs more than the free limits.
Flags and targeting rulesEach flag and its percentage or user-targeting rule must be mapped to an Unleash activation strategy, and Open Source caps instances at 5,000 feature flags per the Unleash pricing page.Export all flag definitions as JSON, delete stale flags before mapping, and map rules in batches with a test checklist for each.
Segments and shared targetingSegments and custom strategies are exported as references only, so they must exist in the target before any import runs.Create shared segments in Unleash first, then import flags that reference them, and confirm names match exactly.
SDK languages and service countEvery application using a ConfigCat SDK needs its SDK swapped or wrapped, and each language adds its own testing path.Group services by language, pilot one service per language, and consider an OpenFeature provider layer so application code changes once.
Partial rollout re-bucketingUsers in percentage rollouts may be assigned to different variants after cutover, which requires a decision and sometimes stakeholder sign-off.Freeze rollout percentages during the cutover window, or accept and document the re-bucketing for each flag before the switch.
CI, webhook and audit integrationsPipelines, notifications and audit trails that call ConfigCat's Public Management API or webhooks need to be rewired to Unleash's Admin API.List every integration before scoping, and retain ConfigCat audit history within its retention window by exporting it early.
Hosting and PostgreSQL 15 or laterRecurring cost covers the server host, the PostgreSQL database, backups and upgrades, and the Unleash server listens on port 4242 per its getting started guide.Size for your actual request volume, reuse existing PostgreSQL platforms where your policies allow, and document the backup and restore procedure.
Edge caching and Enterprise plan choiceThe open-source version of Unleash Edge reaches end of life on December 31, 2026, so scale designs that depend on Edge may need an Enterprise plan, which Unleash prices as Custom Enterprise on annual contracts.Confirm Edge requirements before the design is fixed, and ask Unleash for a written quote covering cloud, self-hosted or hybrid options.

What usually goes wrong and how to prevent it

Most failed ConfigCat-to-Unleash moves fail on details rather than on the SDK swap itself. The cards below cover the places where percentage rollouts, plan limits, licensing, flag hygiene and imports tend to break, with a prevention step for each.

Re-bucketed users in partial rollouts

Percentage rollouts depend on how each system hashes a user into a bucket. Unleash does not reproduce ConfigCat's bucket assignments, so some users who were on the new variant in ConfigCat may see the old one after cutover, and the reverse. This is illustrative but common in any hash-based rollout. Before cutover, decide whether users must keep their current experience, then run both systems in parallel behind an abstraction layer and compare assignments for a sample of users. Confirm the exact hashing and stickiness behavior with Unleash documentation before you rely on it.

Open Source project and environment limits

Unleash Open Source allows one project and two environments per instance. A ConfigCat account with several products or stages can exceed that during import, and the migration stalls halfway through. Count your ConfigCat products and environments before you start, then compare them with the Unleash plan you intend to run. If you need more, price an Enterprise or other paid plan before import begins, not after. Ask Unleash to confirm what counts toward the flag limit on the pricing page.

Unleash Edge end of life for scaled designs

The open-source version of Unleash Edge, the caching layer between SDKs and the Unleash API, reaches end of life on December 31, 2026. A design that puts Edge in front of many SDK clients to reduce load on the server will need a supported path before that date. Decide early whether SDKs connect directly to the server, whether you need Edge at your traffic level, and which plan will support it. Ask Unleash how it recommends OSS Edge users move.

AGPLv3 review for modified servers

Starting with v8.0.0, the Unleash server source moved from Apache 2.0 to AGPLv3, while the official open-source Docker images stay under Apache 2.0. Running unmodified images does not trigger the source obligations described in Unleash's announcement. If your team patches the server, or offers a modified Unleash to others as a service, have legal counsel review the obligations before the change goes live. Record which image tag and version you run.

Missing segments and custom strategies at import

Unleash exports segments and custom strategies only as references, so the import fails or applies incorrectly if the target does not already contain them. ConfigCat targeting often relies on segments shared across flags, which makes this easy to miss. Recreate every segment and custom strategy in the target instance first, using the names from your export, then run the environment import. Verify each imported flag against its ConfigCat source before enabling it for real traffic.

Stale flags left in code

A migration copies every flag, including ones that were already fully rolled out or abandoned. Those flags add evaluation paths, confuse the new dashboard and keep old branches alive in code. Before exporting, list flags that have been constant for a long time, mark owners and remove dead branches in the application. Then migrate only the flags that still control behavior. Reassess each one after cutover, and set a removal date for temporary release flags.

How the move differs by team size and starting point

A single ConfigCat product with a production and one non-production environment is the simplest case. Unleash Open Source is free to self-host and covers one project and two environments, so the move is mostly a matter of exporting flags, recreating them and swapping SDKs. Most of the effort sits in the flag-by-flag mapping, not in infrastructure, because one server and one PostgreSQL database are enough for this footprint.

  • Environment count: Two environments fit a production and staging pair. A third environment requires Enterprise or a separate instance, so decide this before you start.
  • Project limit: Map the product to the single Unleash project. A second product triggers the Enterprise question described in the next tab.
  • Flag cap: The Open Source plan lists 5,000 feature flags per instance on the Unleash pricing page. Count your flags and unused flags before you migrate.
  • Licensing: Running the official Docker images without modification stays under Apache 2.0. Modifying the server moves you to the AGPLv3 terms that apply from v8.0.0.
  • Ongoing work: Plan for upgrades, backups and database maintenance, which are your costs under self-hosting.

Check the environment count, flag count and any custom changes to the server against the Unleash pricing page before you commit to the Open Source edition.

Questions buyers ask before the migration starts

How much effort does moving from ConfigCat to Unleash take?

The effort depends mostly on how many products, environments, configs and targeting rules you have in ConfigCat, and how many services call the SDK. Each flag needs its targeting rules mapped to an Unleash activation strategy, each percentage option needs a matching strategy parameter, and each SDK call site needs to switch to the Unleash client or an OpenFeature provider. Teams with many flags that share targeting logic usually spend more time on mapping and testing than on the server itself. Ask for an inventory of flags, environments and SDK integrations before you ask for a quote, because that inventory is what the scope is built from.

How long does a ConfigCat to Unleash migration take?

The timeline is set by the size of the flag inventory, the number of services that evaluate flags, and how long you need to run both systems in parallel before cutting over. Unleash recommends running both systems in parallel behind an abstraction layer before cutting over, which adds a verification period that you should plan for explicitly. Environment recreation, change control approvals and testing in staging also add time. Agree the timeline in writing as part of a fixed scope, and confirm it against your release calendar and any change freeze windows.

What must our team provide for the migration?

You need to provide administrative access to ConfigCat with rights to read products, configs, environments and flags through the Public Management API, a hosting environment for Unleash with PostgreSQL 15 or later, and named owners who can approve targeting logic for each flag. Engineers must identify every service and SDK that evaluates flags, and someone must confirm which flags are still in use. Security or platform teams should confirm where the server, database and backups will run, and who holds the credentials. Confirm the exact list with your implementation partner before work starts.

Can our own engineers migrate from ConfigCat to Unleash without a partner?

Yes, a capable platform team can do the migration in-house, provided it has time to read the ConfigCat Public Management API, script the export and recreate flags in Unleash. The Unleash documentation describes JSON import and export between instances, but segments and custom strategies are exported only as references, so they must exist in the target before import. Teams that do this alone usually underestimate the mapping work and the parallel-running period. A partner is most useful when the team lacks capacity, when compliance evidence must be produced, or when the cutover carries business risk.

Is Unleash Open Source enough to replace ConfigCat?

It depends on how many projects and environments you run. Unleash Open Source is limited to 1 project and 2 environments with basic roles, and the Unleash pricing page lists a limit of 5,000 feature flags per instance on the free self-hosted tier. Unleash Enterprise adds unlimited projects and environments, single sign-on, SCIM provisioning, project and custom roles, user groups and change requests. If your ConfigCat setup uses several products or more than two environments, the open-source edition will not cover it without an Enterprise license. Map your current structure against these limits before you commit to a design.

How does the AGPLv3 license apply to our self-hosted Unleash deployment?

Starting with Unleash v8.0.0, the server source code moved from Apache 2.0 to AGPLv3, while the official open-source Docker images remain under Apache 2.0 and the SDKs keep their permissive licenses. According to Unleash's blog, the change does not affect teams running the official open-source Docker images without modifying the source. If you modify Unleash and offer it as a public or commercial service, you must publish the source or buy a commercial license. Have your legal team review your intended use, and check the current license files before you pin a version.

What happens to our ConfigCat audit history when retention ends?

Audit history in ConfigCat is kept only within its retention window, so records older than that window may no longer be available in the hosted service. Export the audit log before your plan ends and store it in your own evidence repository, along with the flag definitions and change history you need for audits. Unleash keeps its own change history from the point you start using it, but it does not import ConfigCat's past audit entries. Ask your compliance team which records they must retain, and confirm the ConfigCat retention period in your contract or with ConfigCat directly.

Will users see different flag values during a partial rollout after switching?

Users can be re-bucketed if the new system hashes users differently from ConfigCat, so some users in a percentage rollout may move in or out of a variant at cutover. Before switching, confirm how each platform computes the rollout bucket and whether you can reproduce ConfigCat's assignments in Unleash. Where exact stickiness matters, such as for active experiments or rollouts of user-facing changes, freeze rollout percentages during the cutover window and verify assignments in staging. Document the approach so product owners can accept any remaining re-bucketing knowingly.

When to confirm the decision before you start

Before you export anything, confirm what your ConfigCat plan lets you read through the Public Management API. Products, configs, environments, flags and targeting are the objects you need, and coverage can differ by plan and by the permissions on the token you issue. Ask ConfigCat support, or test with a read-only token against one product, to see whether targeting rules and percentage options come back in full. If any object is missing, plan a manual rebuild for it and record that gap now, not during cutover.

Next, confirm the Unleash edition that fits your project and environment count. Unleash Open Source is limited to 1 project and 2 environments, and the open-source pricing page lists a cap of 5,000 feature flags per instance. If your ConfigCat setup spans several products or more environments, the Open Source edition will not hold it, and you will need to check Enterprise or Pay-As-You-Go pricing with Unleash before you commit. Also confirm which Unleash license terms apply to your use. The AGPLv3 change that starts with v8.0.0 affects teams that modify the server or offer it as a service, so have legal review it against your deployment model.

Finally, confirm your caching design and hosting environment. Decide whether your SDKs will connect straight to the Unleash API or through a caching layer. The open-source version of Unleash Edge reaches end of life on December 31, 2026, so any design that depends on it needs an Enterprise plan or a different plan for scale, and that should be confirmed with Unleash in writing. On the infrastructure side, check that you can run the unleashorg/unleash-server image against PostgreSQL 15 or later, with port 4242 reachable from your applications and admin users. Confirm the database backup, patching and TLS owners in your own environment before the first import.

How DeployOpen scopes, runs and supports the migration

DeployOpen is a Chainscore Labs company that plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For a move from ConfigCat to Unleash, we start with a written scope that covers your products, environments, flags and SDK footprint, then build and verify the Unleash deployment before any traffic moves.

How we scope

  • Inventory every ConfigCat product, config, environment and flag that applications depend on today.
  • Confirm how many Unleash projects and environments you need, since Open Source allows one project and two environments.
  • Agree in writing which percentage rollouts must keep users in their current buckets during cutover.

How we build

  • Deploy the Unleash server against PostgreSQL 15 or later, with the admin UI on port 4242 inside your network.
  • Export ConfigCat definitions through the Public Management API and recreate them as Unleash strategies and variants.
  • Test each SDK swap in staging, and confirm the Unleash Edge design against the end-of-life date for OSS Edge.

How we hand over

  • Document the mapping from each ConfigCat targeting rule to its Unleash activation strategy and segment.
  • Provide runbooks for environment import and export, backups, upgrades and AGPLv3 license review for your use case.
  • Walk your engineering and compliance teams through the parallel run, cutover checklist and rollback steps.

How we support

  • Offer ongoing support, upgrades and continuous testing for the Unleash deployment as a retainer.
  • Re-run configuration checks after each Unleash release, such as v8.2.0, before you adopt it.
  • Confirm with your procurement team what a written quote needs to cover, including licensing tier and hosting scope.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.