Before we meet the tool, we need to understand the pain that made it necessary.

Deploying and releasing are two different things

For many years, software teams treated “deploy” and “release” as the same event. You put new code on the servers, and the moment it landed, every user could see it. That is simple, but it is also risky. A deployment means the new code is now running in production. A release means users can actually see and use the new behavior. When these two are glued together, every deployment is a gamble.

Feature flags split them apart. You deploy the code on Tuesday, but the feature stays hidden. On Thursday, after checking everything, you release it to ten percent of users. On Friday, if all looks healthy, you release it to everyone. The code never changed between Tuesday and Friday. Only a setting changed.

Why big-bang releases hurt

Without flags, teams keep new work on long-lived branches until it is “ready”. Those branches drift away from the main code, and merging them later becomes painful. Releases get bigger, rarer, and scarier. When something breaks, the only fix is to roll back the entire release, which also throws away every good change that shipped with it.

Large technology companies have long used switches in their code to avoid this trap. Facebook, Google, Netflix and many others are widely known to rely on gradual rollouts, dark launches, and experiments as a normal part of how they ship software. The idea is old. What changed is that teams now want a ready-made, shared service for it instead of building a home-grown switch system from scratch.

A short history of Flagsmith

Flagsmith began life under the name Bullet Train, an open-source feature flag service, and was later renamed Flagsmith. It kept its open-source roots. The core platform can be read, run, and modified by anyone, and the company behind it also sells a hosted version and paid plans with extra enterprise features. That mix of open code and optional hosting is a big part of why people choose it.

One sentence first, then we unpack every word in it.

Flagsmith is an open-source feature flag and remote configuration service. It gives you a central dashboard and an API where you define features, decide who sees each one, and let your applications ask, at runtime, what to show.

Feature flag

A feature flag (also called a feature toggle) is a named on/off switch that lives outside your code. Inside your code you write something like “if the new-checkout flag is on, show the new page, otherwise show the old one.” The flag’s value is not stored in the code. It is fetched from Flagsmith. Change the value in the dashboard and the behavior changes, with no new build.

Remote config

Remote config is the cousin of the flag. Instead of only on or off, a feature can carry a value, such as a number, a piece of text, or a small block of settings. For example, a flag called “max-upload-size” could carry the value 25, and tomorrow you change it to 50 without touching the app. This is useful for banner messages, limits, timeouts, button labels, and similar tunable details.

Open source

Open source means the platform’s code is public. You can inspect how it works, run it on your own servers, and avoid being locked to one vendor’s hosting. Some advanced features sit in paid tiers, so always check which plan includes what before you depend on a feature.

Service

Flagsmith is a service, not a library you paste into one app. It runs as its own system with an API. Many different applications, written in many different languages, can all talk to the same Flagsmith and share one source of truth about what is on and off.

Flagsmith organizes everything in layers. Learn these four words and the dashboard will make sense.

Organisation

An organisation is the top-level container. It usually matches your company or business unit. It holds your team members, billing, and all of your projects.

Project

A project usually matches one product or application, for example “Mobile App” or “Customer Portal”. A project owns a list of features. The important rule is that the feature list lives at the project level, so a feature called “new-checkout” exists once for the whole project.

Environment

An environment is a separate copy of the feature states inside a project. Typical environments are Development, Staging, and Production. The same feature can be on in Development, half-on in Staging, and off in Production. Each environment has its own keys so that a test app never accidentally reads production settings.

Feature

A feature is the named thing you control. It exists in every environment, but its state (on or off) and its value can differ per environment. When people say “I created a flag,” they mean they created a feature in a project.

flowchart TD
    ORG["Organisation"] --> P1["Project: Mobile App"]
    ORG --> P2["Project: Customer Portal"]
    P1 --> E1["Environment: Development"]
    P1 --> E2["Environment: Staging"]
    P1 --> E3["Environment: Production"]
    P1 --> F1["Feature: new-checkout"]
    P1 --> F2["Feature: promo-banner-text"]
    F1 -.-> E3
    F2 -.-> E3
    

Why does this layering matter? It gives you safety by default. Developers can experiment freely in Development without any risk to Production, and the same flag name carries through every stage of your delivery pipeline.

Turning a feature on for everybody is easy. The real power is turning it on for the right people.

Identity

An identity is Flagsmith’s name for “one user” (or one device, or one account, whatever you choose). You give each identity a unique ID, such as a user ID from your own database. When your app asks Flagsmith for flags and includes that ID, Flagsmith can give an answer tailored to that specific identity.

Trait

A trait is a fact about an identity. Examples: country, subscription plan, app version, signup date, or “is an employee.” Your application sends traits to Flagsmith, and Flagsmith stores them against the identity. Traits are the raw material for targeting.

Segment

A segment is a saved group defined by rules over traits. For example, “Beta testers” might be every identity whose plan equals “pro” and whose country is one of three you chose. Rules can compare values in several ways, such as equals, does not equal, contains, greater than, or a percentage split. Once a segment exists, you can reuse it on any feature.

Segment overrides

A segment override says: “for this feature, in this environment, when the identity belongs to that segment, use this state and value instead of the default.” Overrides are checked in a priority order, so you can stack several of them. The first matching rule wins.

Beyond a simple switch, Flagsmith can hand out different variations and release features slowly.

Multivariate flags

A normal flag has two outcomes: on or off. A multivariate flag has several possible values, and each value is given a weight. Suppose you are testing three button colors. You can create a flag with the values “blue”, “green”, and “orange”, and assign each a share of your users, for example thirty-three percent each. Flagsmith assigns each identity to one of the values in a stable way, so the same person keeps seeing the same color every time they return.

Percentage rollouts

A percentage rollout releases a feature to a fraction of identities. You start at one percent, watch your dashboards, then move to five, twenty-five, fifty, and one hundred. The choice of who is inside the group is made by turning the identity’s ID, together with the feature, into a repeatable number between zero and one hundred. Because the process is repeatable, an identity that was inside the first one percent stays inside as you grow to ten percent. Nobody flickers in and out.

Remote config values

Every feature can carry a value in addition to its on/off state. This is what makes Flagsmith a remote configuration tool. Values can be text, numbers, or true/false. Teams use them for things like the wording of a banner, the number of items on a page, a retry limit, or the URL of a help center. Changing a value takes effect on the next fetch by your app.

Now we lift the lid and look at the parts that make up a Flagsmith system.

At a high level, Flagsmith has a management side, where people configure flags, and a serving side, where applications fetch them. These two sides have very different needs. The management side must be rich and careful. The serving side must be extremely fast and always available.

The main components

• Dashboard (front end): the web interface where you create features, build segments, and flip switches. It is a single-page web application that talks to the API.
• API (back end): the application server that stores configuration and answers requests. The core Flagsmith API is a Python application built with the Django framework, backed by a relational database such as PostgreSQL.
• Database: the durable store of organisations, projects, environments, features, segments, and audit history.
• SDKs: client libraries for many languages that your applications use to fetch flags without writing raw web requests.
• Edge API: in the hosted service, a separate, globally distributed serving layer built for speed. It answers flag requests from locations close to the user.
• Background workers and caches: components that handle slow jobs such as webhooks and analytics, and that keep hot data close to the API so it does not hit the database on every call.
• Integrations: connectors that send flag changes and usage data to other tools, such as monitoring or analytics platforms.

flowchart LR
    ADMIN["Engineer or Product Manager"] --> DASH["Dashboard"]
    DASH --> API["Flagsmith API"]
    API --> DB[("Relational Database")]
    API --> CACHE["Cache"]
    API --> WORKER["Background Worker"]
    WORKER --> HOOKS["Webhooks and Integrations"]
    API --> EDGE["Edge API and Edge Store"]
    WEB["Web or Mobile App"] --> SDK1["Client SDK"]
    SVC["Backend Service"] --> SDK2["Server SDK"]
    SDK1 --> EDGE
    SDK2 --> EDGE
    SDK2 -.-> API
    

Why separate management from serving?

Think about traffic. A team might change flags a few times a day, but a popular app might ask for flags thousands of times every second. If both jobs shared one database, the busy read traffic could slow down the dashboard, and a dashboard problem could hurt your live app. By copying the final, read-ready configuration into a fast, simple store near the users, the serving path stays quick and the management path stays flexible.

Follow one request from the first line of code to the final answer.

Step by step

When a user opens your app, your code calls the Flagsmith SDK and asks for the flags, usually passing the user’s ID and traits. The SDK sends a web request over a secure connection to Flagsmith. The request includes an environment key, which tells Flagsmith which project and which environment to read.

Flagsmith looks up the environment’s feature list. For each feature it starts with the default state and value. If an identity was supplied, it then loads that identity’s traits, checks the segment overrides in priority order, and applies the first match. If the feature is multivariate, it computes the identity’s stable bucket and picks the matching variation. The final list of states and values is returned to the SDK, which hands it to your code as simple, easy-to-read answers.

sequenceDiagram
    participant U as User App
    participant S as Flagsmith SDK
    participant F as Flagsmith Serving Layer
    participant C as Configuration Store
    U->>S: Get flags for identity 42 with traits
    S->>F: Request with environment key
    F->>C: Load features, segments, overrides
    C-->>F: Environment configuration
    F->>F: Match segments and compute rollout bucket
    F-->>S: Final states and values
    S-->>U: Flag on or off, plus values
    

The environment key

The environment key is both an address and a password. It identifies which environment you want and proves that your app is allowed to read it. Flagsmith uses two kinds, and the difference is important enough that the next chapter explains it fully.

Stable bucketing

A key feature of rollouts is that the same identity gets the same answer on every request. Flagsmith achieves this by running a repeatable calculation over the identity and the feature rather than rolling dice each time. No per-user table of “who got what” is needed. The result is predictable and cheap to compute, even for very large audiences.

Where your code runs changes how it should talk to Flagsmith, and how much it should trust the answer.

Two kinds of applications

A server-side application runs on machines you control, such as a web API or a background job. A client-side application runs on a device you do not control, such as a browser or a phone. This difference matters for secrecy. Anything shipped to a browser or phone can be read by a determined user, so it must never contain anything sensitive.

Two kinds of keys

Flagsmith therefore offers two kinds of environment keys. A client-side environment key is safe to embed in a web page or mobile app. It can fetch the flags for an identity but cannot read the full rule set. A server-side environment key is a secret. It can read the complete environment configuration, including every segment rule, so it must live only on your servers, never in a browser bundle or app package.

Remote evaluation

By default, SDKs use remote evaluation. Each time the app asks for flags, Flagsmith does the matching work and returns the final answers. This is simple, keeps rules private, and works well for client-side apps. Its cost is a network round trip for each fetch.

Local evaluation

Server-side SDKs can use local evaluation. In this mode the SDK downloads the whole environment document, including the segment rules, and then does the matching inside your own process. It refreshes that document on a regular schedule, commonly about once a minute, which you can adjust. Because answers are computed in memory, each lookup is extremely fast and does not need a network call at all.

Choosing between them

A busy backend that checks flags thousands of times per second usually benefits from local evaluation, since it removes both latency and load. A mobile app usually uses remote evaluation with a client-side key. Some SDKs also let you cache the last known answers so the app can start quickly and refresh in the background. Check the documentation for your language, since features differ slightly between SDKs.

A flag is born, grows, and, if the team is disciplined, is retired.

The healthiest way to think about a flag is as something with a short life. It is created for a purpose, used while that purpose is live, and removed when the purpose has been served. Teams that forget the last step end up with a swamp of old switches.

flowchart LR
    A["Create flag, off everywhere"] --> B["Merge code behind the flag"]
    B --> C["Turn on in Development and Staging"]
    C --> D["Release to small percentage in Production"]
    D --> E["Grow to 100 percent"]
    E --> F["Remove flag and old code"]
    D -->|"Problem found"| G["Turn off, fix, retry"]
    G --> D
    

Change control and scheduling

Flagsmith supports workflows that make production changes safer. Paid tiers include change requests, where one person proposes a flag change and another approves it, much like a code review. Changes can also be scheduled for a future time, so a launch can happen at nine in the morning without anyone needing to be awake and clicking. Every change is written to an audit log that records who changed what, and when.

Flag checks sit on the hot path of your product, so they must be fast and must scale.

Why flag speed matters

If every page view depends on a flag, then a slow flag service means a slow product. Worse, a feature flag platform that fails would turn a tool meant to improve safety into a new way to cause outages. For this reason, serving flags is designed to be read-heavy, cache-friendly, and simple.

Read-heavy by nature

Flag data is read far more often than it is written. A flag might be changed once a week but read a hundred million times. Systems like this respond very well to caching and to copying data close to the reader. Almost all of Flagsmith’s scaling story is about making reads cheap.

The Edge API

In its hosted offering, Flagsmith uses a dedicated serving layer, often called the Edge API, which stores a read-optimized copy of each environment in a fast key-value store and runs on a globally distributed, serverless foundation. Requests are answered from a location near the caller, which keeps the round trip short. When someone changes a flag in the dashboard, the core API writes the change to its database and then updates the edge copy so that the serving layer sees the new state.

Scaling a self-hosted deployment

If you run Flagsmith yourself, you scale it in familiar ways. Run several copies of the API behind a load balancer. Add a cache so repeated reads do not hit the database. Use database replicas for read traffic. Move slow jobs, such as sending webhooks, to background workers so they never slow down a flag request. For many teams, the largest saving comes not from the server at all, but from using local evaluation in their SDKs, which turns thousands of requests into one refresh per minute per server.

What should your app do when the flag service is unreachable? You must decide this before it happens.

No network service is perfect. Links drop, deployments fail, and data centers have bad days. A well-built use of Flagsmith assumes that, one day, a flag request will fail, and plans for that moment.

Safe defaults

Every flag check in your code should have a default value: the answer to use when no answer can be obtained. Most SDKs let you register a default handler for this. The golden rule is that the default should be the safest, most boring behavior, which is usually the old, well-tested path. A new, unfinished feature should default to off. A kill switch for a failing dependency should default to its protective state.

Caching and offline modes

SDKs can remember the last good answer and keep using it while the service is unreachable. With local evaluation, the in-memory copy of the environment keeps working even if the network disappears, and refreshes resume when the connection returns. Some SDKs also support an offline mode, where flags are loaded from a file or a stored copy instead of the network, which is helpful for tests and for locked-down environments.

Timeouts

Never let a flag request wait forever. A short timeout followed by a fall back to the default keeps a slow flag service from becoming a slow product.

flowchart TD
    Q["App asks for a flag"] --> N{"Answer received in time?"}
    N -->|"Yes"| U["Use the live answer"]
    N -->|"No"| K{"Cached answer available?"}
    K -->|"Yes"| C["Use the cached answer"]
    K -->|"No"| D["Use the safe default"]
    

High availability for self-hosted setups

When you host Flagsmith yourself, apply the standard recipe. Run multiple API instances across separate zones. Use a managed or replicated database with automatic failover and regular backups. Put a load balancer with health checks in front. Test your restore procedure before you need it. Remember too that the flag service should be among the best-monitored parts of your platform, because so many other things depend on it.

A flag controls behavior, and behavior can be sensitive. Treat flag access like production access.

Protect the keys

Server-side keys are secrets and should be stored in a secrets manager, injected at runtime, and rotated when people leave or when exposure is suspected. Client-side keys are public by design, so assume they can be read by anyone and never use a flag alone to protect something that truly must stay secret.

Flags are not access control

This is a very common mistake. A flag that hides a button in the browser does not stop a determined person from calling the underlying API directly. If a feature must be restricted, the server behind it must check permission. Use flags to decide what to show, and use proper authorization to decide what is allowed.

Be careful with traits

Traits are data you send to Flagsmith. Send only what you need for targeting, such as a plan name or country, and avoid sending personal or sensitive details like email addresses, health information, or payment data. Less data stored means less data that could ever be exposed.

People and permissions

Within the dashboard, limit who can change Production. A common pattern is to let everyone edit Development, a wider group edit Staging, and a small group, or an approval workflow, control Production. Paid tiers add finer-grained roles and single sign-on options for larger organisations. Together with the audit log, this gives you a trail of every change.

Data location and self-hosting

Some organisations have rules about where data may live. Self-hosting Flagsmith, or using a private cloud option, keeps configuration and traits inside infrastructure you control. This is a main reason regulated companies pick an open-source platform.

A flag change is a production change. It deserves the same visibility as a deployment.

The audit log

Flagsmith records who changed which flag, in which environment, and when. When something strange happens at two in the afternoon, the first question is “what changed?” The audit log answers it in seconds.

Webhooks

Webhooks are automatic messages that Flagsmith sends to a web address you choose whenever something happens, such as a flag change. They let your own systems react. For example, a webhook can post a message to a chat channel, trigger a cache refresh, or record the change in an internal ticket.

Integrations

Flagsmith can connect to other tools. Observability platforms such as Datadog and New Relic can receive flag change events, so that a graph of errors can show a marker at the exact moment a flag was flipped. Analytics tools such as Amplitude, Mixpanel, and Segment can receive information about which variation each user was given, so you can compare outcomes between groups. Chat tools can announce changes to your team. The exact list changes over time, so check the current integrations page.

What to watch

• Error rates and response times before and after a flag change.
• The health and response time of the Flagsmith service itself, if you host it.
• How stale local-evaluation copies are, to catch an SDK that has stopped refreshing.
• The number of flags in each project, and how old they are, to keep clutter under control.
• Business numbers, such as conversion, for the group that received the new feature versus the group that did not.

Flagsmith meets you where your rules and budget are.

One of the clearest strengths of Flagsmith is choice. You can let the company run it for you, or you can run it yourself, and the dashboard and concepts stay the same either way.

How to choose

A small team that wants to move quickly usually starts with the hosted service. A company with strict data rules, or one that must run inside its own network, usually chooses self-hosting or a private cloud. Because the platform is open source, you are not trapped: many teams begin hosted and later move to self-hosted, or the other way around, as their needs change.

What self-hosting asks of you

Running it yourself means you own upgrades, backups, scaling, monitoring, and security patches. The core pieces are the API service, the front end, a relational database, and optionally a cache and background worker. None of this is exotic, but it is real work, and it must be done carefully because so many applications will lean on it.

Not all flags are alike. Knowing the type tells you how long it should live and who should own it.

A widely used way to sort flags into groups comes from software engineers who studied how teams use them. The four groups below cover almost every real case.

Related practices these patterns enable

• Dark launch: run new code in production for real traffic, but hide its result from users to see how it behaves.
• Canary release: expose the change to a small group first, like a canary in a coal mine, and widen only if all is calm.
• Trunk-based development: everyone merges small changes to one main branch often, and flags hide anything unfinished.
• Ring deployment: release in widening circles, from staff to friendly customers to everyone.

flowchart LR
    R0["Staff only"] --> R1["Beta testers segment"]
    R1 --> R2["1 percent of all users"]
    R2 --> R3["25 percent of all users"]
    R3 --> R4["Everyone"]
    

Feature flags are powerful, and every powerful tool can be misused. These are the traps teams fall into most often.

More mistakes to avoid

• Unsafe defaults: a default of “on” for an unfinished feature turns a service outage into a feature leak.
• Vague names: a flag called “test2” tells nobody anything. Use names that say what they do, such as “checkout-new-payment-form”.
• Evaluating flags deep in the code: scatter checks everywhere and the behavior becomes hard to follow. Decide near the entry point and pass the decision along.
• Changing Production without a plan: flipping a flag has the same power as a deployment. Announce it, watch it, and know how to undo it.
• Treating flags as a config database: remote config is for small, tunable values. Large data sets belong in a real database.
• Ignoring client-side limits: a flag value shipped to a browser is visible to the user. Never put secrets in a flag value.

A short list of habits that separate calm teams from chaotic ones.

A sensible starting routine

If your team is new to Flagsmith, begin with one low-risk feature. Create a project, set up Development and Production environments, add a single flag, and wire the SDK into one service. Practice flipping the flag, watching the result, and reading the audit log. Only after that feels natural should you introduce segments, percentage rollouts, and approvals. Growing in small steps teaches the habits at the same time as the tool.

An honest look at what Flagsmith gives you and what it costs.

How it compares with other tools

The feature flag space has several well-known options. The table below gives a fair, high-level picture. Details and prices change often, so confirm current facts on each vendor’s site before deciding.

Build versus adopt

Many teams start with a simple home-made switch, such as a setting in a file or a table in the database. It works for a while. Then come requests for percentage rollouts, per-user targeting, an audit trail, scheduled changes, and a dashboard for non-engineers. Each is a small project, and together they become a product. This is the point where adopting a platform such as Flagsmith usually costs less than continuing to build.

An open standard

An open specification called OpenFeature defines a common way for code to ask for flags, so that the application code is not tied to one vendor. Providers exist that connect OpenFeature to Flagsmith, which can make a later switch easier. Check the current documentation for the providers available for your language.

Here are the ways teams commonly put a platform like Flagsmith to work. These are described as general practices, not as claims about any one customer.

When one product is made of many small services, a flag decision must stay consistent across all of them.

A modern product is often built from dozens of small services, each owned by a different team. A single user action, such as placing an order, may travel through an API gateway, a cart service, a pricing service, a payment service, and a notification service. If each one asks Flagsmith for the same flag at a different moment, they might, in rare cases, get different answers. That can produce confusing behavior, such as a page that shows a new price but a receipt that uses the old one.

Decide once, pass it along

The simplest cure is to make the decision at the edge of the request, usually in the first service that receives it, and then pass the result along with the request, for example in a header or a request context. Downstream services read the passed value instead of asking again. This also saves calls and makes the whole request behave as one unit.

Use one identity everywhere

For targeting to be consistent, every service must use the same identity ID for the same user. If the cart service identifies a person by an account number and the pricing service by an email address, the same person will land in different segments and different rollout buckets. Agree on one identity format and use it everywhere.

Version skew

During a rollout, different copies of a service may run different versions of the code. A flag that is on may reach a copy that does not yet know how to handle it. The safe habit is to deploy code that understands the new behavior everywhere first, and only then turn the flag on. In other words, flip the flag after the code is fully deployed, not before.

flowchart LR
    USER["User request"] --> GW["API Gateway"]
    GW -->|"Evaluate flags once"| FS["Flagsmith"]
    FS --> GW
    GW -->|"Pass decision in request context"| CART["Cart Service"]
    CART --> PRICE["Pricing Service"]
    PRICE --> PAY["Payment Service"]
    

Shared flags or separate flags?

A single feature that spans several services can use one shared flag, which keeps things simple but ties the teams together. Alternatively, each service can own its own flag, which gives teams independence but needs coordination on the order of turning them on. A reasonable rule of thumb is to share a flag only when the services must change behavior at the same time, and to keep flags separate in all other cases.

Flags give you more paths through your code, and every path needs a test.

Test both sides of the switch

Every flag creates two versions of your product: one with the feature on, and one with it off. Both versions reach real users at some point, so both must be tested. A common mistake is to test only the new path and discover later that turning the flag off breaks the old one.

Control flags in tests

Automated tests should not depend on a live flag service that someone might change at any moment. Instead, tests can use the offline mode of an SDK, or a small fake that returns the exact flag values the test needs. That makes tests fast, repeatable, and independent of network conditions. A separate set of end-to-end tests can still run against a dedicated Staging environment, where the flags are set on purpose.

Keep the combinations small

Two flags mean four combinations. Five flags mean thirty-two. You cannot test every combination of every flag in a large product, so reduce the problem. Keep flags independent, retire them quickly, and test only the combinations that are meant to happen together.

Flags and the delivery pipeline

In a pipeline where code flows automatically from commit to production, flags are the brake and the steering wheel. The pipeline deploys the code as often as it likes, while the flag decides what users see. This is the idea behind trunk-based development: small changes land on the main branch often, and anything unfinished stays hidden behind a flag. Branches that live for weeks, and the painful merges that follow, become rare.

flowchart LR
    C["Commit to main branch"] --> B["Build and automated tests"]
    B --> S["Deploy to Staging"]
    S --> P["Deploy to Production, flag off"]
    P --> R["Gradual rollout using the flag"]
    R --> X["Flag removed in a later change"]
    

Rolling back with a flag versus rolling back code

When a release goes wrong, the old way is to redeploy the previous version, which can take many minutes and touches every server. Turning a flag off is far quicker, since it changes one setting and needs no deployment. This is called a fast rollback, and it is one of the most loved benefits of the whole approach. Keep in mind it only works if the flag was put in before the release, so decide early which risky changes deserve one.

Tools are easy. Habits and rules are what keep them healthy as the team grows.

Who is allowed to do what

As more people touch flags, you need clear rules. A simple model has three tiers. Anyone on the engineering team may create and change flags in Development. A wider group, including testers and product managers, may change them in Staging. A small group, or an approval step, controls Production. Where an approval workflow is available, require it for flags that touch money, safety, or legal rules.

Tags and organisation

Flagsmith lets you label features with tags. Use them to record the team that owns the flag, the type of flag, and whether it is scheduled for removal. A quick filter on a tag such as “release” or “remove-soon” turns a long list into a clean-up checklist.

Where the cost really comes from

Cost has two sides. The first is the money you pay: a hosted plan is usually priced by things such as the number of requests, seats, or projects, while a self-hosted setup costs servers and the time of the people who run it. The second is the hidden cost: every flag adds a code path that must be understood, tested, and eventually removed. Teams often find the hidden cost larger than the bill. Cutting down the number of live flags is usually the best savings.

To keep the request bill sensible, use local evaluation on servers so they call the service rarely, and cache answers in apps so that every screen change does not trigger a new request.

A regular flag review

Hold a short review every month or two. List every flag older than a chosen age, such as ninety days. For each one, ask three questions: is it still needed, who owns it, and when will it be removed? Anything that fails these questions goes onto the cleanup list. This single habit prevents more trouble than almost any technical measure.

A gentle path from “never used it” to “using it with confidence”.

When several rules could apply to the same user, Flagsmith needs a clear order of winners. Knowing that order prevents surprises.

So far we have said that the first matching rule wins. Let us look at the full ladder of decisions, from the most specific to the most general, because designing targeting well means understanding which rule beats which.

The ladder of precedence

For a given feature in a given environment, Flagsmith works through several layers. The most specific layer is an identity override, which pins a feature to a particular state or value for one named identity. Below that are the segment overrides, checked in priority order. At the bottom is the environment default, which applies when nothing more specific matches. Whenever a more specific layer has an opinion, it beats every layer beneath it.

flowchart TD
    S["Flag request for an identity"] --> A{"Identity override exists?"}
    A -->|"Yes"| R1["Use identity override"]
    A -->|"No"| B{"A segment override matches?"}
    B -->|"Yes, highest priority first"| R2["Use that segment override"]
    B -->|"No"| R3["Use environment default"]
    

Priority between segments

Because one identity can belong to many segments, the order of the segment overrides matters. Imagine that “all employees” has an override that turns a feature on, while “users in a restricted country” has an override that turns it off. If an employee lives in a restricted country, which rule should win? You decide by arranging the priority. Put the rule that must never be broken, such as the legal restriction, above the rule that is only a convenience.

Designing good segment rules

• Prefer stable traits. Traits like plan name or country change rarely. Traits that change often, such as “items in cart”, can make a user flicker between segments and see unstable behavior.
• Keep rules readable. If a segment needs a paragraph to explain, it is too complicated. Split it into smaller, named segments.
• Name segments by meaning. “Beta testers” explains itself. “Segment 7” does not.
• Reuse segments. A segment is defined once and used on many features. This keeps your definition of “enterprise customer” in a single place.
• Think about missing traits. If your app forgets to send a trait, rules based on it will not match. Decide what the safe behavior is for people without the trait.

Percentage splits inside segments

A percentage rule can also be placed inside a segment. For instance, “plan equals pro” and “in the first twenty percent of identities”. The first condition narrows who is considered, and the second decides how many of them are chosen. This is a clean way to say “roll this out to twenty percent of our paying customers only.”

Persistent traits and one-time traits

By default, traits that your app sends are stored against the identity, which lets later requests reuse them. For some data, such as a value that is only meaningful for the current moment, you may prefer not to store it. Newer SDKs offer a way to send such traits for a single evaluation without saving them. Whether you store or skip a trait is partly a privacy choice, so use the one-time approach for anything you do not need to keep.

Distributed systems rarely agree instantly. Flag systems are no exception, and it helps to know exactly how late “late” can be.

When you press a button in the dashboard, the change does not appear everywhere at the same instant. It travels through several steps, and each step can add a small delay. Understanding those steps lets you set honest expectations for your team.

The path of a change

First, the dashboard sends the change to the core API, which writes it to the database. That write is the moment the change becomes official. Next, in a setup with a serving layer at the edge, the new state is copied to that layer. After that, there may be caches in between, such as a cache inside the API, a content delivery layer in front, or a cache inside your own SDK. Finally, apps that fetch flags on a schedule will pick up the new value the next time they fetch.

sequenceDiagram
    participant Admin as Dashboard User
    participant Core as Core API
    participant DB as Database
    participant Edge as Serving Layer
    participant SDK as SDK in App
    Admin->>Core: Change flag
    Core->>DB: Save change
    Core->>Edge: Publish new state
    SDK->>Edge: Next scheduled refresh
    Edge-->>SDK: New state
    

Eventual consistency

This kind of delay is called eventual consistency: if nothing else changes, every part of the system will soon agree, but for a short window, some parts may still hold the older value. In the language of distributed systems, flag platforms favor availability and speed over perfectly instant agreement, which is the right trade for a read-heavy service whose answers change rarely.

What this means in practice

• Do not expect a switch to be instant. For flags that protect production, know how long your slowest path takes, and plan for that.
• Shorter refresh means faster change but more calls. Choose an interval that matches how urgent changes are. A kill switch may deserve a short interval, while a banner wording does not.
• Do not use flags for exact timing. If something must happen at a precise second, use a scheduled change and allow a margin rather than relying on millisecond accuracy across all servers.
• One user, many servers. For a short window, two servers might disagree about the same user. Passing the decision with the request, as shown earlier, hides this.

Two people editing at once

Humans also cause conflicts. If two engineers change the same flag at nearly the same moment, the later save normally wins. The audit log keeps both changes, so you can see exactly what happened. Using change requests for sensitive flags prevents silent overwrites, since one person proposes and another reviews.

Stale data and the safe fallback

Staleness is also a risk for apps that cache for a long time, such as a mobile app that stores flags and does not refresh for hours. Decide how old an answer is allowed to get. If a flag is a kill switch, a stale “on” is dangerous, so such flags should be refreshed often. If it only controls a decoration, an old answer is harmless.

Apps that run on a user’s own device bring special problems: slow networks, offline moments, and long release cycles.

Why mobile apps love remote config

Shipping a new version of a mobile app means building it, submitting it to an app store, waiting for review, and then waiting for users to update. Some users never update at all. A feature flag changes this. If the code for a feature was shipped in advance, you can turn it on, off, or adjust it at any time, without asking the app store for permission or the user for an update. This is among the most valuable uses of Flagsmith for mobile teams.

The first launch problem

When someone opens an app for the very first time, there is no cached answer, and the network may be slow. The app must decide what to show immediately. This is why safe defaults, built into the app itself, are so important. A good approach is to ship the app with sensible defaults, fetch fresh flags in the background, and apply them at a calm moment, such as the next screen or the next launch.

Avoiding flicker

If a page first shows the old design and then suddenly swaps to the new one when the flag arrives, the user sees a flicker, which looks broken. There are three common ways to prevent it. You can wait briefly for the flags before drawing the screen. You can fetch the flags on the server and include them in the page that is sent to the browser. Or you can cache the previous answer and use it immediately while refreshing in the background. The right choice depends on how much delay your users will tolerate.

Offline users

Phones lose signal in lifts, trains, and tunnels. An app that uses Flagsmith should keep working in these moments, using the last known flags. Test your app with airplane mode switched on. If the result is a blank screen, your defaults and caching need work.

Older versions in the wild

Because some people never update, your Production environment will serve flags to many app versions at once. A flag that is safe for the newest version might crash an old one that does not understand it. Handle this by sending the app version as a trait and creating a segment such as “version at least 5.2”. Then only apps that can handle the feature will receive it.

Keep secrets out of apps

Remember that the client-side key, and every flag value, is visible to anyone who inspects the app or the page. Use flags to change behavior and appearance, and keep real secrets, such as private API keys, on your servers.

Numbers make design choices clear. Here is a simple, made-up example to show why local evaluation matters so much.

The following numbers are illustrative, chosen to be easy to follow. They are not measurements of any real system.

The setup

Imagine an online store whose backend runs on one hundred servers. Together they handle about twenty thousand page requests every second, and each request checks about five flags. That is one hundred thousand flag checks every second.

With remote evaluation on every check

If each check were a network request to the flag service, the service would need to answer one hundred thousand requests per second, all day long. That is a heavy load, and each of those requests adds a small delay to a customer’s page. If the flag service is slow for even a moment, every page waits.

With one fetch per request

A better design fetches all five flags together, one call per page request. The load falls to twenty thousand calls per second, five times lighter, but it is still a constant stream of traffic that grows with your popularity.

With local evaluation

With local evaluation, each of the hundred servers downloads the environment once a minute. That is about one hundred downloads per minute across the whole fleet, which is under two per second. The one hundred thousand checks per second are all answered from memory, with no network trip. The load on the flag service has fallen by a factor of more than fifty thousand, and customers’ pages no longer depend on the flag service being fast.

flowchart LR
    subgraph A["Remote on every check"]
        A1["100 servers"] -->|"100,000 calls per second"| A2["Flag service"]
    end
    subgraph B["Local evaluation"]
        B1["100 servers"] -->|"about 2 refreshes per second"| B2["Flag service"]
    end
    

The trade you accept

Local evaluation is not free. Each server holds the complete rule set in memory, so it is a little behind during the refresh interval, and server keys must be protected, since they can read all rules. For a busy backend these costs are small compared with the gain. For browsers and phones, where the rules should stay private, remote evaluation with a client-side key is still the right choice, and caching keeps the request count down.

Many teams already have some kind of switches in their code. Here is a sensible way to move to a shared platform without breaking anything.

Start by taking inventory

List every existing switch, whether it lives in a config file, an environment variable, or a database table. For each one, write down what it controls, who changes it, and whether it is still used. You will usually find that a good number of switches are dead and can simply be deleted, before you migrate anything.

Put a thin layer in front

Create a small wrapper in your own code with a method such as “is this feature enabled for this user”. All your application code calls this wrapper, and the wrapper decides where the answer comes from. This has two benefits. You can switch the source from the old system to Flagsmith one flag at a time. And later, if you ever change tools or adopt the OpenFeature standard, you only change one file.

Migrate in small steps

• Pick the least risky switch first and recreate it in Flagsmith with the same value.
• Make the wrapper read the flag from both systems and log any disagreement, without acting on the new one yet.
• When the two agree for a good period, let the wrapper trust Flagsmith.
• Delete the old switch and its code.
• Repeat for the next switch, moving to the more important ones as your confidence grows.

flowchart LR
    CODE["Application code"] --> WRAP["Wrapper: is feature enabled"]
    WRAP -->|"Before migration"| OLD["Old switch source"]
    WRAP -->|"After migration"| FS["Flagsmith"]
    

Agree on names and owners during the move

A migration is the perfect moment to fix naming and ownership. Give each flag a clean name, add a description, and set an owner and a planned removal date. It is far easier to start with good habits than to repair bad ones later.

Handle people as well as code

Teach the people who will use the dashboard. Product managers should know how to read a flag, see its state in each environment, and understand who is allowed to change Production. Support staff may need a way to check whether a customer has a feature. A short guide and one demonstration usually do more than a long document.

A gradual rollout is only useful if you know what to look at, and what result means “keep going” or “stop”.

Many teams turn on a flag for five percent of users and then simply hope for the best. That wastes the main benefit of a gradual rollout. The whole point of starting small is to learn something before the audience gets bigger, so you need to decide, before you start, what you will measure and what will make you stop.

Two kinds of measures

Guardrail metrics protect the health of the product. They answer “did we break anything?” Common examples are the rate of errors, how long pages take to load, how often the app crashes, and how many support requests arrive. Goal metrics measure whether the feature does its job. They answer “is this better?” Examples are the share of visitors who finish a purchase, the number of people who use a new tool, or how long people stay.

Compare groups, not before and after

A flag gives you something valuable: two groups of users at the same time, one with the feature and one without. This is far more trustworthy than comparing this week with last week, because the weather, the news, and the day of the week affect both groups equally. If errors are higher only in the group with the flag on, the flag is the likely cause.

Write the rules before you begin

Beware of small samples

At one percent of a small audience, only a handful of people see the feature. A few random errors can look like a disaster, and a few lucky successes can look like a triumph. Be patient. For a rare event such as a purchase, you may need many days to collect enough data. For a clear failure, such as a crash on startup, even a small sample is enough to stop.

Do not stop at launch

Some problems appear only later: a memory leak that grows for hours, a monthly billing job that runs once, or a behavior that confuses users after a week. Keep watching a feature for a reasonable time after it reaches everyone, and keep the flag in place until you are confident. Only then remove it.

Closing the loop

When a rollout ends, write a short note about what you learned. Did the guardrails catch anything? Did the goal metric improve? Was the rollout too slow or too fast? These notes become your team’s memory, so the next rollout starts a little wiser than the last.

Targeting needs information about people. How much you send, and where it lives, is a decision worth making carefully.

Flagsmith itself does not need to know much about your users. Everything depends on what your application chooses to send. The safest habit is to treat the flag service as a place for small, plain facts, never as a place for personal records.

Send the minimum

Ask of every trait: “do we truly need this to decide who sees a feature?” A plan name, a country, an app version, and a customer type are usually enough. A full name, a home address, a phone number, or health and financial details are almost never needed, and sending them creates risk with no benefit.

Use pseudonymous identifiers

The identity ID can be an internal number, such as a customer ID from your database, rather than an email address or a name. If the data were ever exposed, a bare number tells an outsider very little. Your own systems can still map it back to a person when needed.

Know where the data lives

Some laws and company policies say where personal data may be stored or processed. When you use a hosted service, find out which regions are used for storage and which are used for serving, and whether choices exist. When data location is a strict rule, self-hosting or a dedicated private option lets you keep everything inside regions and networks you control.

Respect the right to be forgotten

Many privacy rules let people ask for their data to be deleted. If you store traits against identities, make sure you have a way to remove an identity and its traits when such a request arrives. Plan this in advance rather than discovering the gap when a request lands in your inbox.

Control who can see what in the dashboard

The dashboard shows identities and traits to those who have access. Give access only to people who need it, use the roles and permissions available in your plan, and remove accounts when people change teams or leave. Keep the audit log on, so you can answer questions about who changed or viewed what.

A short checklist

• List every trait you send and write one line saying why it is needed.
• Remove any trait that identifies a person directly or reveals sensitive details.
• Use internal IDs instead of emails for identities.
• Confirm where your data is stored and whether it meets your policy.
• Create a procedure to delete an identity on request.
• Review dashboard access every quarter.

Every important word from this guide in one place, for quick reference.

Flagsmith turns release risk into a dial you control. It separates the act of deploying code from the act of showing it to users, and it gives you precise, reversible control over who sees what. Used with care, it makes teams faster and calmer. Used carelessly, it becomes one more thing to maintain, so discipline matters as much as the tool.