Before we can talk about where the decision is made, we need to be clear about what the decision is.

A quick refresher on feature flags

A feature flag is a named switch that lives outside your code. Your code asks, “Is the new search page enabled for this person?” and a configuration, which you can change at any time from a dashboard, supplies the answer. This lets a team ship code quietly, turn it on for a few people, widen the audience slowly, and turn it off instantly if something goes wrong.

Flagsmith is an open-source platform that manages these switches. Besides plain on/off flags, it supports remote config values, which are numbers or pieces of text that a flag can carry. It also supports segments, which are groups of users defined by rules, and multivariate flags, which hand out several different values to different percentages of people.

What does “evaluation” mean?

A flag in the dashboard is only a recipe. It might say: “This feature is off for everybody, except it is on for users in the premium segment, except it is also on for one named tester, and ten percent of users should get the blue button while ninety percent get the green button.” That recipe is not an answer. Someone, or something, must look at one specific user and work out the single final answer for that user. This act of turning a recipe plus a user into a final answer is called evaluation.

The big question: who evaluates?

Evaluation has to happen somewhere. In Flagsmith there are exactly two places it can happen. It can happen on Flagsmith’s servers, which is remote evaluation. Or it can happen inside your own server application, which is local evaluation. Everything in the rest of this guide flows from that single choice.

The idea is simple. The complexity lives in the details, which we will unpack one layer at a time.

The definition

Remote evaluation means that every time your application needs flags, it makes a request to the Flagsmith API, and the API computes the right values and returns them. The SDK in your application is little more than a messenger: it carries your question out and your answer back. The rules, the segments, and the percentage calculations never leave Flagsmith’s side.

In remote mode, an SDK usually asks one of two questions. The first is, “What are the flags for this environment in general?” That question has no user attached, so the answer is the environment defaults. The second is, “What are the flags for this particular identity, who has these traits?” That second question is where segments, personal overrides, and percentage splits come into play.

Why it is the default

Remote evaluation is the default because it is the simplest and safest place to start. There is nothing to configure beyond a key. The answers are always computed using the latest rules, because the rules are read at the moment of the request. The application never needs to understand how segments work. And the same method works on every platform, from a tiny script to a mobile app on a phone with a weak signal.

What travels in each direction

Notice what is not sent back: the segment definitions, the percentage rules, the list of other users, or other environments. The caller receives only what it needs to behave correctly for one user.

Where remote evaluation is used

All client-side SDKs, meaning those that run in browsers and phones, use remote evaluation only. Server-side SDKs, which run in your backend in languages such as Python, Java, Go, Ruby, and Node, use remote evaluation by default and can optionally be switched to local evaluation. So when people say, “Flagsmith evaluates remotely”, they usually mean, “it is working in its normal, out-of-the-box way”.

You cannot fully understand one mode without seeing the other beside it.

How local evaluation works, briefly

In local evaluation, a server-side SDK uses a secret server-side key to download a complete snapshot of the environment, including every feature, segment, rule, and override. This snapshot is often called the environment document. The SDK keeps it in memory and refreshes it on a timer, for example once a minute. When your code asks for flags for a user, the SDK works out the answer on the spot, using the snapshot, with no network call at all.

Side-by-side comparison

Same answer, different route

An important design goal is that both modes should give the same answer for the same user and the same rules. Flagsmith calculates percentage splits in a repeatable way from the user’s identity and the feature, so a person who falls in the “ten percent” group remains in it no matter which mode computed the answer. Still, because the two modes read data at different moments, they can briefly disagree right after a change, which we explore in the freshness chapter.

Eight small ideas appear in every remote evaluation. Learn them once and the rest is easy.

Environments and keys

An environment is a separate copy of your flag settings, such as Development, Staging, and Production. Each has its own environment key. When your app sends a request, the key tells Flagsmith which environment’s rules to use. A client-side key is meant to be public and can only read flags. A server-side key is secret and has broader rights.

Features and their states

A feature is the named item you control. In each environment it has an enabled state, either on or off, and optionally a value. The pair of state and value is what a remote evaluation returns for every feature.

Identity and traits

An identity is a stable label for one user, such as an internal account number. A trait is a small fact about that identity, such as their plan, country, or app version. In remote mode, you can send traits along with the request, and Flagsmith can store them against the identity for later.

Segments

A segment is a saved group defined by rules over traits, for example “plan equals premium and country equals Germany”. Segments let you target a feature at a group instead of at everyone.

Overrides

An override replaces the default for a segment or a single identity. A personal override outranks a segment override, and a segment override outranks the environment default.

Multivariate options

A multivariate feature has several possible values and a percentage split among them. Remote evaluation picks the one value that belongs to the user, in a repeatable way.

The priority ladder

When several rules could apply, Flagsmith follows a fixed order. A personal identity override wins first. If there is none, a matching segment override applies. If there is none of those either, the environment default is used. This ordering is the reason a named tester can always see a feature that is off for everyone else.

Let us zoom out and see every piece involved when remote evaluation answers a request.

The picture

The system has a control side, where humans create and edit flags, and a delivery side, where applications read flags at high speed. Between them sits a store of data that holds environments, features, segments, and identities. Remote evaluation lives on the delivery side.

flowchart LR
  APP["Your Application with Flagsmith SDK"] -->|"HTTPS request with environment key"| LB["Load Balancer and CDN"]
  LB --> API1["Flagsmith API Node 1"]
  LB --> API2["Flagsmith API Node 2"]
  API1 --> ENGINE["Evaluation Engine"]
  API2 --> ENGINE
  ENGINE --> CACHE["Fast Cache"]
  ENGINE --> STORE[("Environment, Segment and Identity Store")]
  DASH["Dashboard"] --> CORE["Core API"]
  CORE --> STORE
  ENGINE -->|"Finished list of flags"| APP
  APP -->|"Optional usage analytics"| LB

Meet the components

Separating reads from writes

A product might change its flags a few dozen times a day but read them millions of times. Systems with this shape work best when the read path is separated from the write path, so that heavy reading never slows down editing. Flagsmith’s hosted service uses a distributed delivery layer for SDK traffic, so busy applications do not compete with the people working in the dashboard.

Let us follow a single request from the moment your code asks for a flag until the answer is in your hands.

Step one: your code asks

Somewhere in your application, a piece of code needs a decision. It asks the SDK for the flags of a user. The SDK checks whether it already has a fresh enough copy of the answer in its own memory. If it does, it returns that immediately and the story ends. If not, it prepares a network request.

Step two: building the request

The SDK attaches the environment key to the request so that Flagsmith knows which environment to use. If you gave an identity, it includes the identity and any traits you supplied. The request travels over a secure connection, which protects it from being read or changed in transit.

Step three: the front door

The request reaches the load balancer, which selects a healthy API node. The node first checks the key. An unknown or revoked key is rejected at once. A valid key identifies one environment, and the node loads that environment’s rules, usually from its fast cache, and only occasionally from the main store.

Step four: finding the identity

If an identity was provided, the node looks it up. If it has been seen before, its stored traits and any personal overrides are loaded. Traits sent in the current request are merged in, and, depending on how you sent them, saved for later. If the identity is brand new, it is created or treated as new, depending on the endpoint and settings.

Step five: the evaluation engine decides

For each feature in the environment, the engine runs the priority ladder from Chapter 4. It checks for an identity override first. Then it checks every segment the identity belongs to, by applying each segment’s rules to the identity’s traits. Then it falls back to the environment default. For multivariate features, it turns the identity and the feature into a number in a repeatable way, and uses that number to pick a value according to the percentage split.

Step six: the reply

The engine assembles a compact list with one entry per feature, each containing the name, the enabled state, and the value. The node sends it back. The SDK stores it in memory, optionally for a short time so repeated calls do not trigger repeated requests, and hands the answers to your code.

A remote evaluation request comes in two flavours, and choosing the right flavour affects both correctness and cost.

Flavour one: environment flags

The first flavour asks, “Give me the flags for this environment.” There is no identity, so no segment or personal rule can apply, and the reply is the environment defaults. This is the cheapest and simplest request. It is perfect for settings that are the same for everyone, such as a global maintenance banner or a site-wide kill switch.

Flavour two: identity flags

The second flavour asks, “Give me the flags for this identity, who has these traits.” The reply reflects segments, personal overrides, and percentage splits. This is what you need for gradual rollouts, targeting by plan or country, and experiments. It does more work, because Flagsmith must look up the identity and evaluate rules, and it may also store the traits you send.

Persistent traits and transient traits

When you send traits with an identity request, there are two possible intentions. In one, you want Flagsmith to remember the traits, so they are available in future requests and visible in the dashboard. In the other, you want to use the traits for this evaluation only and then forget them. This second kind is called a transient trait, and it is helpful for facts that change constantly or that you would rather not store, such as the current basket value or a one-time session detail. The details of how to mark traits as transient vary by SDK, so check your documentation.

Why remembering traits is useful

Stored traits make identity evaluation smarter over time. A mobile app might send the country once at sign-up. Later, a web page can ask for flags for the same identity without resending it, and Flagsmith still knows the country. Support staff can also open an identity in the dashboard and see exactly which flags that person receives, which turns mysterious bug reports into quick investigations.

A flag has a long life in the dashboard and thousands of short lives in requests. Let us follow both.

From dashboard click to user answer

Suppose a product manager turns on a feature called “new-search” for a segment of premium users. Here is what happens, in order, when that premium user next triggers a remote evaluation.

sequenceDiagram
  participant PM as Product Manager
  participant DASH as Dashboard and Core API
  participant STORE as Data Store
  participant API as Flagsmith API
  participant ENG as Evaluation Engine
  participant APP as Your Application
  PM->>DASH: Enable new-search for premium segment
  DASH->>STORE: Save change
  APP->>API: Request flags for identity with traits
  API->>STORE: Load environment rules and identity
  STORE-->>API: Rules, segments, overrides, stored traits
  API->>ENG: Evaluate every feature
  ENG-->>API: One answer per feature
  API-->>APP: Finished list of flags
  APP->>APP: Show new search to premium user

Life of a flag in the dashboard

Life of one evaluation

One evaluation is short. It is born when your code asks, lives for a few milliseconds as a request travels and is processed, and dies when its answer is used or cached. The important insight is that remote evaluation reads the rules at the moment of the request. A change made one second ago in the dashboard is already part of the next request’s answer, unless something along the way, such as an SDK cache or a CDN, held on to an older copy.

The engine is the heart of remote evaluation. Understanding how it thinks makes every strange result easy to explain.

How a segment is matched

A segment is a bundle of rules. Each rule looks at one trait and applies a test, such as “equals”, “does not equal”, “contains”, “is greater than”, “is in a list”, or “matches a pattern”. Rules can be grouped. A group can require that all its rules match, or that any of them match. Groups can sit inside groups, which allows rules such as “plan is premium and (country is India or country is Germany)”.

When the engine evaluates an identity, it takes the identity’s traits and tests every segment. An identity may belong to zero, one, or many segments at the same time. If several segments override the same feature, the engine needs a tie-breaker, and Flagsmith uses a documented priority order for segment overrides. You can see and change that order in the dashboard. Treat the priority list as part of your design, not an afterthought.

What happens when a trait is missing

A rule can only test a trait that exists. If the identity has never been given a country, a rule about country cannot match. For “not equal” style rules, treatment of a missing trait can surprise people, so test such rules with an identity that lacks the trait. When something refuses to match, the first thing to check is whether the trait was sent at all, and whether it was spelled and capitalised the same way as in the rule.

How a percentage split stays stable

Percentage rollouts and multivariate splits must be fair and repeatable. If the engine used a random number each time, a user could see the new feature on one request and the old one on the next. Instead, the engine combines the identity and the feature into a single value and maps it onto a number line from zero to one hundred. The same inputs always produce the same number, so a given person stays on the same side of the line, request after request, server after server.

A rollout set to ten percent means that identities whose number falls below ten receive the feature. Raising it to twenty keeps everyone who already had it and adds more. Nobody who was in drops out when you widen the circle, which is exactly what a careful rollout needs.

Why the feature name matters in the split

If the number depended on the identity alone, the same lucky ten percent of users would always be first in every rollout of every feature, and they would become unwilling test subjects for everything. Mixing the feature into the calculation shuffles who is early for each feature, which spreads the risk of early exposure fairly across your user base.

The honest cost of remote evaluation is time. Every evaluation that is not cached must cross a network.

Where the time goes

The delay for one remote evaluation is the sum of several small pieces. First comes the network trip from your server or device to Flagsmith and back, which depends on distance and quality of connection. Then comes the secure connection setup, which is slower the first time and quicker when a connection is reused. Then queueing and processing inside Flagsmith, which is usually small. Finally comes the transfer of the reply, which depends on how many features you have and how large their values are.

Why this matters for a busy server

Suppose a web page needs five flag decisions, and your server asks Flagsmith five times in a row, each trip taking forty milliseconds. That is two hundred milliseconds added to the page, with nothing else done. Now imagine that happening for every visitor. The cost is not only slower pages. Your server holds each request open while it waits, which uses up memory and worker capacity, so traffic spikes hurt more than they should.

Five ways to keep it quick

Do not put remote calls inside tight loops

A classic mistake is evaluating a flag inside a loop that processes thousands of items, such as checking “is the new price rule enabled?” once for each product on a page. If each check is a network call, the page will take minutes. Evaluate once before the loop, store the answer in a plain variable, and use that variable inside the loop.

A flag service sits on the critical path of almost every request. It must handle crowds without breaking.

Understanding the load

Imagine an application with ten million daily users. If each user triggers three flag requests a day, that is thirty million requests per day, about three hundred and fifty per second on average. Real traffic is lumpy. A marketing campaign or a push notification can multiply the rate by fifty within a minute. A remote evaluation service must be built for the peak, not the average.

How the load is spread

flowchart TD
  CLIENTS["Millions of Clients and Servers"] --> EDGE["CDN and Edge Layer"]
  EDGE --> LB["Load Balancer"]
  LB --> N1["API Node A"]
  LB --> N2["API Node B"]
  LB --> N3["API Node C"]
  N1 --> RC["Shared Fast Cache"]
  N2 --> RC
  N3 --> RC
  RC --> DB[("Primary Data Store")]
  DB --> REP[("Read Replica or Standby")]
  AUTO["Auto Scaling Rules"] -.->|"add or remove nodes"| LB

The scaling toolbox

Horizontal scaling means adding more identical API nodes rather than making one node bigger. Because evaluation is mostly a read operation with no memory of earlier requests inside the node, any node can answer any request, which makes this style of scaling simple. Caching keeps the most common data, such as an environment’s rules, in memory so the main database is rarely touched. Replication keeps extra copies of the data, so reads can spread and a failure does not lose everything. Auto scaling adds nodes when traffic rises and removes them when it falls.

Hosted versus self-hosted scale

If you use Flagsmith’s hosted service, the provider runs a distributed delivery layer and is responsible for scaling it. If you host Flagsmith yourself, you own that job. You will run several API nodes behind a load balancer, give them a managed database with backups, add a cache, and monitor request rates and latency. Plan your capacity from the peak traffic you expect, with comfortable headroom.

Protecting the service

Remote evaluation puts a network and another company’s service between your code and a decision. Plan for that service being slow or gone.

What can go wrong

Several things can fail on the way to an answer. The network can drop packets or become slow. The service can be overloaded, restarting, or temporarily down. A key can be wrong or revoked. A certificate can expire. A firewall in your own network can block outgoing traffic. Each of these produces the same visible result: your code did not receive an answer.

Decide the failure behaviour in advance

The question that matters is not “what if it fails?” but “what do we want to happen when it fails?” The answer is usually one of three choices, and you choose per flag. Fail closed means treating the feature as off, which is the safe default for new or risky features. Fail open means treating the feature as on, which suits essential behaviour such as fraud checks that must never be skipped. Use the last known value means carrying on with the most recent good answer, which suits features where a slightly old decision is better than a surprise change.

flowchart TD
  ASK["Code needs a flag"] --> MEM{"Fresh answer in SDK memory?"}
  MEM -->|"Yes"| USE["Use it"]
  MEM -->|"No"| CALL["Call Flagsmith with a short timeout"]
  CALL --> OK{"Answer received?"}
  OK -->|"Yes"| SAVE["Store in memory and use it"]
  OK -->|"No"| LAST{"Last known good answer exists?"}
  LAST -->|"Yes"| STALE["Use last known answer and retry later"]
  LAST -->|"No"| DEF["Use safe default for this flag"]

Timeouts, retries, and back-off

A timeout limits how long your code will wait. Without one, a stalled request can hold a worker forever. A retry tries again after a failure, which helps with brief glitches. But retries can make a bad situation worse when thousands of callers retry together. Exponential back-off makes each retry wait longer than the last, and jitter adds a small random amount so callers do not all strike at the same moment. Together they let a struggling service recover instead of being flattened again.

Circuit breakers

A circuit breaker stops calling a service that keeps failing. After several failures in a row, the breaker “opens”, and your code immediately uses the fallback without even trying the network. After a pause, it lets a single test call through. If that works, the breaker closes and normal service resumes. This protects both your application, which stops wasting time on doomed calls, and the failing service, which gets room to recover.

Offline and fallback options

Many server-side SDKs let you supply default values through a handler that is used when the API cannot be reached. Some also offer an offline mode where the SDK reads flags from a local file or from a snapshot you provide, never calling the network. These are valuable for tests, for isolated environments, and as an emergency parachute. Check your SDK’s documentation for the exact options.

Caching is how remote evaluation becomes fast enough for busy systems. It is also where most freshness surprises come from.

Cache layers

Between a flag change and a user’s screen there can be several caches, and each has its own lifetime. The SDK memory cache holds a user’s answers for a short while. The CDN or edge cache may hold repeated identical responses for seconds. The server-side cache inside Flagsmith holds environment rules. And, on devices, a persistent cache may keep the last answers across restarts. Each layer trades a little freshness for a lot of speed.

Choosing a cache lifetime

Ask a single question: how long can a wrong answer survive without causing harm? For a cosmetic experiment, five minutes may be fine. For a kill switch that protects a payment system, thirty seconds may already be too long. You can give different flags different freshness needs by using separate caches or by treating a small set of critical flags specially.

Cache keys must include the identity

When you cache identity-level answers, the cache key must include the identity and, ideally, a fingerprint of the traits. If you cache by environment only, user A’s personalised answer may be handed to user B. This is a subtle and serious bug, because it shows people features they should not have. Always make the key as specific as the question.

Stale-while-revalidate

A popular technique is to serve the slightly old cached answer immediately while quietly fetching a fresh one in the background, ready for the next request. The user never waits, and the cache keeps itself current. The price is that one unlucky request may see an answer that is a few seconds out of date, which is usually acceptable.

Remote evaluation starts out fresh. Every layer you add to speed it up makes it a little less so. Here is how to think about that honestly.

The freshness spectrum

With no caching at all, a flag change in the dashboard shows up on the very next request. With a one-minute application cache, a change may take up to a minute to reach every server, and different servers may hold different ages of answer at the same moment. With a persistent device cache, a user’s phone may keep an older answer until the next refresh. None of these is wrong. They are design choices.

Eventual consistency in plain words

Because many caches refresh independently, two users, or two servers, can briefly see different answers to the same question. They will all converge on the newest answer shortly afterwards. This behaviour is called eventual consistency, and nearly all large-scale systems accept it in exchange for speed and availability.

In the language of distributed systems, when the network is unreliable you must choose between always answering and always giving the newest answer. Flag systems nearly always choose to keep answering, using cached or default values, because an application that works with a slightly old flag is far better than one that stops.

When consistency really matters

A few situations demand that two parts of your system agree at the same instant. If your front end shows a new price display but your backend still computes the old price, customers see confusing totals. For such cases, make one place the single source of truth. Evaluate the flag once on the server, and send the result to the front end as part of the response, so both sides use the same decision.

Read your own writes

When a person changes a flag in the dashboard and immediately tests the result, they expect to see it. If an application cache holds the old answer, they may conclude that the change did not work and change it again, which creates confusion. Teams often shorten cache lifetimes in Staging, or provide a way to bypass the cache for testers, so changes can be verified at once.

Remote evaluation has a quiet security advantage: the rules stay where they are, and only finished answers travel.

The rulebook never leaves

Because the engine runs on Flagsmith’s servers, the caller never receives the segment definitions, the list of other features’ targeting, or the percentage rules. This is the reason client-side SDKs can safely run in a browser. A curious user opening the developer tools sees only the flags that apply to them, not your product roadmap or your customer segments.

Keys and what they can do

Keep the two key types firmly apart. The client-side key can be shipped in apps because it only reads flags for the identity you give it. The server-side key is a secret. It belongs in your backend’s secret storage, never in source code, logs, mobile apps, or web pages. If a server-side key leaks, treat it as compromised: revoke it and issue a new one.

Privacy of identities and traits

In remote mode, Flagsmith may store identities and traits you send. These are data about people. Use pseudonymous identities, such as an internal account number rather than an email, and send only what you need for targeting. If you serve users in regions with strict privacy laws, tell users what you collect, and consider self-hosting or a regional deployment if data must stay in a specific place. Transient traits let you use a fact for one evaluation without storing it.

Remote versus local, from a security view

Local evaluation downloads a full snapshot of the environment, so the process holding it knows all your rules. That is fine in a well-protected backend, but it makes the secret key and the snapshot more sensitive. Remote evaluation reveals less, because every caller gets only its own answers. If you cannot protect a process fully, remote mode is the more conservative choice.

Because remote evaluation depends on a network call, you must be able to see how that call is behaving.

What to measure

Measure the success rate of flag requests, the latency at the median and at the slow tail, the fallback rate, meaning how often your code had to use a default or an old value, the cache hit rate, and the request volume over time. Averages hide trouble. Always look at the slowest one percent of requests, because that is where your unhappiest users live.

Logging with care

Log enough to investigate: the environment, the feature name, whether the answer came from the network, the cache, or a default, and how long it took. Avoid logging full traits or identities in ordinary logs, since logs are widely readable and long-lived. When you need detail to solve a bug, turn on verbose SDK logging temporarily in a test environment.

Tie flags to everything else you watch

The best practice is to attach the active flag values to your error reports, traces, and business events. When your error tracker shows that crashes doubled, and every crashing session has “new-search equals on”, you have found the cause within minutes. Flagsmith offers integrations with common analytics and monitoring tools so this context can flow automatically.

Alerts worth having

• Failed flag requests rising above a normal level for several minutes.
• Latency tail rising beyond the budget you set for flag lookups.
• Fallback rate rising, meaning users are not receiving real decisions.
• Request volume spiking far above the usual pattern.
• Error spike right after a flag change, which points straight at the change.

The audit trail

Flagsmith records who changed what and when. In an incident, the first question is always, “What changed recently?” A visible, searchable change log turns a long investigation into a one-minute check. Surface recent flag changes inside your incident tools if you can.

Every remote evaluation is a request, and requests are the unit by which many hosted services measure usage.

Why volume grows faster than you expect

If every page view or API call on your side triggers a flag request, the number of requests grows in step with your traffic. A product with a million daily page views and four flag lookups per view produces four million requests a day. If the usage is metered, that can become a real line in your bill. Even for a self-hosted setup, more requests means more servers.

Ways to reduce request volume

The cheapest request is the one you never make. Fetch all flags once per user per visit instead of once per flag. Cache answers for a short and sensible time. Use environment-level requests for flags that do not vary by user. Avoid calling the API from places that run constantly, such as every cell of a spreadsheet job or every iteration of a loop. And consider local evaluation for high-volume backend services, which we cover in the next chapter.

Know your plan and limits

Hosted plans and self-hosted deployments have different rules about request limits and fair use, and those rules change over time. Check the current terms for your plan, and set an alert on your own usage so a bug does not surprise you at the end of the month.

Remote evaluation is the right default, not the right answer for every system. Here is how to tell when another mode fits better.

Signs that remote mode is straining

Watch for a few warning signs. Your flag lookups show up as a noticeable slice of request latency. Your flag request volume is large, steady, and growing. Your service has strict speed targets, measured in single-digit milliseconds. You run in an environment with unreliable or slow access to the flag service. Or you evaluate flags for many different users inside one backend process, such as a batch job or an API gateway. These all point toward evaluating inside your own process.

What you gain with local evaluation

Local evaluation answers in memory, so lookups become almost free. Request volume to Flagsmith drops to a small, steady refresh. Your service keeps working through a short outage of the flag service, because it already holds the rules. And you no longer pay a network trip inside your hottest code paths.

What you give up

The first cost is freshness: changes arrive on the next refresh, not instantly. The second is exposure: your process now holds the whole environment’s rules, so the server-side key and the process must be well protected. The third is memory and processing: your service stores the snapshot and runs the engine. The fourth is trait storage: in local mode, traits you pass are generally used only for that evaluation and are not saved back to Flagsmith, so features that depend on remembered traits need extra thought. And local evaluation is available only for server-side SDKs, never for browsers or phones.

flowchart TD
  START["Where does your code run?"] --> Q1{"Browser or mobile app?"}
  Q1 -->|"Yes"| REMOTE1["Remote evaluation is the only option"]
  Q1 -->|"No, a trusted backend"| Q2{"Strict latency or very high request volume?"}
  Q2 -->|"No"| REMOTE2["Stay with remote evaluation and add a short cache"]
  Q2 -->|"Yes"| Q3{"Can you tolerate changes arriving after a short refresh delay?"}
  Q3 -->|"No"| REMOTE3["Remote evaluation with careful caching for critical flags"]
  Q3 -->|"Yes"| Q4{"Can you protect the server-side key and snapshot?"}
  Q4 -->|"Yes"| LOCAL["Consider local evaluation"]
  Q4 -->|"No"| REMOTE4["Stay with remote evaluation"]

A mixed approach is normal

You do not have to choose one mode for your whole company. A busy internal service might use local evaluation for speed, while your website and apps use remote evaluation because they must. A small, rarely used admin tool can stay remote forever with no cache at all. Match the mode to the job.

Teams that run remote evaluation well tend to reach for the same handful of patterns.

The flag gateway in depth

The flag gateway is the single most useful pattern. Instead of calling the SDK directly from fifty places, create one small module with a clear job: given a user, return the flags, applying a timeout, a short cache, a circuit breaker, and the safe defaults. Every other part of your code uses that module. When you later change cache lifetimes, switch some services to local evaluation, or replace the SDK, you change one place.

Keep the decision near the boundary

Check each flag in one place, close to the edge of the feature, and hand the rest of the code a plain choice between two behaviours. A flag check scattered across twenty files is a flag nobody dares remove. A flag checked once, in a clearly named spot, can be deleted in an afternoon.

The two-path rule

Every flag gives your product two versions: with the feature and without. Both must be tested. Keep the number of live flags small, and retire them promptly. Ten independent flags create over a thousand combinations, and nobody tests all of them.

Strangler-style migration

Flags are excellent for replacing an old system step by step. Build the new path beside the old one, route a small group to it, compare results, and grow the group until the old path carries no traffic. Then delete the old code. The flag is the steering wheel of the whole migration.

Most remote evaluation trouble comes from a small set of repeat offences. Learn to spot them early.

Everyday slips

• Wrong environment. Using the Production key in a test, or editing Production when you meant Staging.
• Trait spelling mismatch. Sending “Premium” when the segment expects “premium”.
• Forgetting the off path. Testing only with the flag on, then finding the rollback broken.
• Sending too many traits. Large or sensitive traits slow requests and raise privacy risk.
• Ignoring failure modes. Never testing what happens when the flag service is unreachable.

Flags make products flexible, which makes testing and debugging more interesting. A clear method keeps both calm.

Testing layers

Troubleshooting: the flag always shows its default

This almost always means no successful answer arrived. Check the key and that it belongs to the right environment. Check the address of the service, especially for self-hosted setups. Check for firewalls, proxies, or missing network permission. Check that your code did not read the flag before the SDK finished loading. And check your logs for timeouts or certificate errors.

Troubleshooting: on in the dashboard, off for my user

Here the identity is probably not matching your rule. Confirm the identity string is the one you think it is. Confirm the traits were sent, with exactly the spelling and capitalisation the segment expects. Remember the priority ladder: a personal override beats a segment, and a segment beats the default. And confirm you changed the same environment your application is using.

Troubleshooting: changes take too long to appear

This is cache timing. List every cache between the dashboard and the user: the SDK memory cache, any shared cache you run, any CDN, and any device cache. The longest lifetime among them sets the worst-case delay. Shorten the lifetime for that flag, or provide a bypass for testers.

Troubleshooting: different answers on different servers

Two servers holding caches of different ages can disagree for a short moment. If the disagreement lasts long, check that all servers use the same environment key, the same SDK version, and the same cache settings.

Where the Flagsmith API runs shapes your latency, your control, and your legal comfort.

Latency and placement

Because remote evaluation is a network call, distance matters. If your servers run in one region and the flag service runs in another continent, every uncached call pays for that journey. Place your Flagsmith endpoint, hosted or self-hosted, in the same region as the services that call it most. For a worldwide audience, rely on a distributed edge layer or run several regional instances.

What a self-hosted setup involves

You will typically run the API as several identical copies behind a load balancer, connect them to a managed database with regular backups, place a cache in front of the busiest reads, and add monitoring on request rate, errors, and latency. Spread copies across several availability zones, which are separate buildings within a region, so a single failure cannot take the service down. Practise restoring from backup, because an untested backup is another kind of hope.

A friendly address

Put the service on a clear address under your own domain where you can. It looks professional, avoids some content blockers for browser traffic, and lets you move the service later without changing every application, because the address your code uses never has to change.

Upgrades

If you self-host, upgrade Flagsmith like any other important system. Try new versions in Staging, read the release notes, keep a rollback ready, and upgrade during a quiet period.

Deciding who sees what is half the story. Learning whether the change helped is the other half.

Why remote mode suits experiments

An experiment needs three things: a fair split of users, a consistent experience for each user, and a way to link the outcome back to the variant. Remote evaluation provides the first two directly. The engine places each identity into a variant using a repeatable calculation, so a person keeps the same variant on every visit, whichever server or device handles the request. Because the decision comes from one central place, your web, mobile, and backend code all agree about which variant a person belongs to.

Linking outcomes to variants

Flagsmith decides the variant, but measuring success normally happens in your analytics tool. The practical approach is to attach the variant to every relevant event, such as “order completed”, so you can later compare groups. Flagsmith offers integrations with common analytics tools to help with this. The important habit is to record the variant at the moment the user actually experiences the difference, not merely when the request is made.

Good experiment habits

• Define success first. Pick the measure before you start, so you do not search for a flattering result afterwards.
• Keep a control group. A group that sees the current experience is your yardstick.
• Run through full weekly cycles. Tuesday shoppers differ from Saturday shoppers.
• Change one thing at a time. Overlapping experiments on the same screen blur the result.
• Wait for enough users. Small differences on small audiences are often luck.

Ending an experiment cleanly

When a clear winner emerges, make its value the default for everyone, remove the losing variants and the experiment code, and archive the flag. An experiment flag is short-lived work, and it deserves the same clean-up discipline as a release flag.

A server-side process handles thousands of different people, which raises questions a single phone app never faces.

One SDK instance, many identities

A phone app has one user. A backend service has thousands of users passing through at once. You should create one SDK instance when the service starts and share it across all requests, rather than creating a new one for every request. A shared instance reuses network connections and any internal caches. For each incoming request, you ask that shared instance for the flags of that request’s user.

Per-request context

At the start of each request, work out who the user is and what traits matter, ask for the flags once, and attach the result to the request’s context, the bundle of facts that travels with that request through your code. Every function that needs a flag reads it from that bundle. This gives you one network call per request at most, consistent answers within the request, and easy testing, since a test can simply supply a ready-made bundle.

Business customers and tenants

Many products serve other companies, called tenants. Often the flag decision depends on the company, not the individual person: “this customer has bought the analytics add-on”. A common approach is to use the company’s identifier as the identity, or to send the company’s plan and region as traits on each person’s identity. Choose the approach that matches how your rules are written, and keep it consistent across all services so every part of your product reaches the same decision.

Background jobs and queues

Jobs that run later, such as sending emails or building reports, still need decisions. The safest approach is usually to evaluate the flag when the job is created and store the result with the job, so the job behaves as the user’s experience was at that moment. Evaluating again hours later can give a different answer after a rollout change, which can confuse users who saw the earlier behaviour.

If one of your services outgrows remote mode, move it with care, not with a leap.

Prove the need first

Before changing anything, gather evidence. Measure how much time flag lookups take in that service. Count how many flag requests it sends. Check whether failures of the flag service have hurt it. If the numbers are small, a short cache in the remote setup is much cheaper and safer than a mode change.

A step-by-step migration

What to watch afterwards

After the move, expect lookup time to fall to almost nothing and request volume to the flag service to drop sharply. Watch memory use of the service, since it now holds the rules. Watch that snapshots keep refreshing on time, and set an alert if a refresh fails repeatedly, because a service running on a very old snapshot is quietly serving old decisions. Remember that the refresh delay means a kill switch will take up to one interval to take effect in that service.

If you remember nothing else, remember these habits. They separate calm, boring flag usage from exciting incidents.

Setting up

• One environment per stage. Development, Staging, and Production each get their own key.
• Right key, right place. Client key on devices, server-side key in your secrets store only.
• Build a flag gateway. One module owns timeouts, caching, and defaults.
• Write the safe default for every flag and the reason behind it.

Making requests

• Fetch once per request, then read from the result.
• Always set a timeout and use a circuit breaker for repeated failures.
• Use environment-level questions for flags that do not vary by user.
• Use stable identities and keep traits small and non-sensitive.
• Use transient traits for facts you do not want stored.

Caching

• Pick lifetimes by risk. Short for critical flags, longer for cosmetic ones.
• Include the identity in every cache key.
• Consider stale-while-revalidate for smooth speed with quiet refresh.

Operating

• Watch the four signals: latency, traffic, errors, and fallback rate.
• Limit who can change Production and require approvals for sensitive flags.
• Keep an audit trail visible during incidents.
• Roll out in small steps with metrics checked between each step.

Cleaning up

• Remove the code first, then archive the flag.
• Use usage data to prove a flag is unused before deleting it.
• Review old flags monthly. Fifteen minutes of review prevents years of clutter.

No design is perfect. Remote evaluation gives you real strengths and real costs, and you should pick with open eyes.

Key trade-offs in detail

Thinking in CAP terms

When the network between your application and the flag service breaks, you must choose between staying available with a possibly old answer and refusing to answer until you can be sure. Flag systems nearly always favour staying available, because an application that keeps working with a slightly old flag is better than one that stops. That is why defaults and last-known-good values are central to a safe design.

Let us watch every idea from this guide work together in one realistic example.

The scenario

FreshCart, a fictional online grocery company, runs a website, phone apps, and a family of backend services serving several million people. The team has built a new delivery-slot picker and wants to release it carefully. They use Flagsmith. Their website and apps use client-side SDKs, which always evaluate remotely. Their backend services use server-side SDKs, which start in remote mode.

The journey

What made it work

Every layer did its job. A gateway kept timeouts, caching, and defaults in one place. Stable identities kept users in consistent buckets. Remote evaluation kept the rules private and the setup simple. A circuit breaker and safe defaults made a short outage invisible. Server-side decisions kept money logic honest. And a measured move to local evaluation fixed the one hot spot without disturbing anything else.

A quick reference for every important word used in this guide.

Short answers to the questions people ask most often about remote evaluation.

Remote evaluation lets a small, simple caller ask a powerful central brain for finished decisions.

You began with a simple problem: your application must decide, for each user, which features to show. Flagsmith’s answer, in its default mode, is to keep the rules and the decision-making on its own servers and send back only the finished answers. That choice is the source of both its greatest strengths, which are simplicity, privacy of rules, and always-current decisions, and its main costs, which are a network trip and a runtime dependency. Everything else in this guide is about getting the strengths while managing the costs.