Before we open the SDK, we need to understand the problem it solves: separating “the code is on the server” from “users can see the feature”.

What is a feature flag?

A feature flag (also called a feature toggle) is a named switch that your code checks before deciding what to do. If the switch is on, the code runs the new behaviour. If it is off, the code runs the old behaviour. The important part is that the switch lives outside your code, in a place you can change at any time without rebuilding or redeploying anything.

A flag can be as simple as “on or off”. It can also carry a small piece of information, such as a number, a word, or a short piece of text. Flagsmith calls these remote config values. For example, a flag named “max_upload_size” could carry the number 25, and you could later change it to 50 from the dashboard without touching a single line of code.

Deploying is not the same as releasing

This is the single most important idea in the whole topic. Deploying means copying new code onto your servers. Releasing means letting real users experience what that code does. Without flags, these two things happen at the same moment, so every deployment is a small gamble. With flags, you deploy the code hidden behind an “off” switch, check that the deployment itself is healthy, and then release the feature slowly: first to your own team, then to one percent of users, then ten percent, then everyone.

Large engineering teams rely on this style of working. Facebook has described an internal system called Gatekeeper that lets engineers expose a change to a chosen slice of users. Etsy became well known for deploying to production dozens of times per day, using configuration flags to keep unfinished work invisible. The practice is common because it turns risky big-bang launches into a series of small, reversible steps.

So what is Flagsmith?

Flagsmith is a feature flag and remote configuration platform. It is open source, which means you can read its code and run it yourself on your own infrastructure. It is also offered as a hosted service, called Flagsmith Cloud, if you prefer not to run anything. Either way, you get a web dashboard where people create flags and decide who sees what, plus an API and a set of libraries that your applications use to read those decisions.

What is an SDK, and what makes it “server-side”?

An SDK (software development kit) is a ready-made library that you add to your project so you do not have to write all the plumbing yourself. The Flagsmith SDK knows how to authenticate, how to ask for flags, how to understand the answers, and what to do when something goes wrong. You simply ask it a question like “is this feature on for this user?” and it hands back an answer.

The word server-side means the SDK runs inside code that you control and that users cannot inspect: a web API, a background worker, a scheduled job, a microservice. The opposite, client-side, means code that runs on the user’s own device, such as a web browser or a phone app. This difference sounds small, but it changes almost everything about how the SDK is designed, which is why the rest of this guide is devoted to it.

Flagsmith uses a handful of building blocks. Once these eight words feel familiar, everything else in the SDK will make sense.

Flagsmith organises everything in a simple hierarchy. At the top sits your organisation (your company). Inside it you create projects, usually one per product or application. Inside each project you create environments, such as development, staging, and production. Inside each environment live your features. The big benefit of this layout is that the same flag can be on in development and off in production, with no risk of the two affecting each other.

Why identity matters so much

Imagine you want to show a new checkout page to exactly 10 percent of users. If every request was decided by a random coin flip, the same person could see the new page in the morning and the old page in the afternoon. That is confusing and makes testing meaningless. Flagsmith avoids this by turning the identity into a stable number using a hashing method, then checking whether that number falls inside the chosen percentage. The same identity always lands on the same side. We will look at this more closely in the chapter on how evaluation works.

On/off flag or remote config value?

A common beginner question is when to use a plain on/off flag and when to use a value. Use an on/off flag when the question is “should this behaviour happen at all?” Examples are showing a new page, enabling a new payment route, or switching on a background job. Use a remote config value when the question is “how much, how often, or which one?” Examples are the number of items per page, the retry limit for a partner service, or the name of the search provider to call. Many features use both: the flag says whether the new behaviour is active, and the value tunes it.

Values deserve discipline. Keep them small, since they travel with every document or response. Give them clear units in the name, such as “timeout_seconds” rather than just “timeout”, so that nobody enters 5000 thinking of milliseconds when the code expects seconds. Validate them in your code, with sensible minimum and maximum limits, because a typing mistake in a dashboard should never be able to turn a ten-second timeout into ten hours.

Flagsmith ships two families of SDKs. Knowing which family you are holding, and why they differ, prevents the most serious mistake people make.

Client-side SDKs run in places you do not control. A browser tab can be opened by anyone, and anyone can press a key and look at everything inside it. A mobile app can be taken apart by a curious person with the right tools. Because of that, a client-side SDK must be built on one assumption: everything it knows can become public. It therefore uses a public identifier called the client-side environment ID, and it only asks the server one narrow question at a time: “what are the flags for this one identity?”

Server-side SDKs live in a trusted place. Nobody can open your data centre or your container and read what is in memory. This trust allows the SDK to use a server-side environment key, which is a secret. A secret key unlocks extra abilities, in particular the ability to download the complete rulebook for an environment and evaluate it yourself. That ability is the foundation of local evaluation, which we will study in detail soon.

Why the rulebook must stay secret

The downloadable rulebook, called the environment document, contains every segment rule, every percentage split, and every identity override in the environment. If it reached a browser, a curious user could learn how your pricing tiers are targeted, which beta testers exist, and which unreleased features are waiting in the wings. That is why only the secret key can fetch it, and why the secret key must never be placed in front-end code.

A practical rule of thumb helps here: use the server-side SDK whenever a decision protects something valuable, such as access to a paid feature, a data export, or a risky operation. Flags in the browser only change what the user sees. Flags on the server change what the user is allowed to do. Never rely on a client-side flag alone to guard something that matters.

Here is the full picture of the parts that cooperate every time your backend asks a question about a flag.

Let us walk through the diagram below from left to right. An engineer works in the Flagsmith dashboard, a web interface, to create flags and change them. The dashboard saves changes through the Flagsmith API, which stores them in a primary database. The platform also keeps a fast, read-optimised copy of each environment ready for the SDKs to use. On Flagsmith Cloud this fast path is called the Edge API, a globally distributed service built so that flag reads stay quick even for customers far from any single data centre. If you self-host, you run the API yourself and can place it close to your own services.

flowchart LR
  Dev["Engineer using the Dashboard"] --> API["Flagsmith API"]
  API --> DB[("Primary Database")]
  API --> Edge["Edge API and cached environment data"]
  Users["End Users"] --> GW["API Gateway"]
  GW --> LB["Load Balancer"]
  subgraph Platform["Your Backend Platform"]
    LB --> S1["Service Instance 1 with SDK"]
    LB --> S2["Service Instance 2 with SDK"]
    LB --> S3["Service Instance 3 with SDK"]
  end
  S1 --> Edge
  S2 --> Edge
  S3 --> Edge

On the right side of the picture sits your platform. Real users reach you through an API gateway (the front door that handles authentication and routing), which hands requests to a load balancer (the traffic officer that spreads requests across identical copies of your service). Each copy of your service contains its own Flagsmith SDK client. Notice something important: there is no shared “flag server” inside your platform. Each instance fends for itself, which makes the design simple and removes a central point of failure.

The parts inside the SDK

Two more supporting parts are worth knowing about. Webhooks let Flagsmith notify other systems when a flag changes, which is handy for audit trails and chat alerts. And an optional piece called the Edge Proxy can sit inside your own network, caching environment data close to your services, which we will revisit when we compare ways of running the SDK.

Remote evaluation is the default way the server-side SDK works. It is the simplest to understand, so it is the right place to start.

In remote evaluation, Flagsmith does the thinking. Your service sends a question across the internet, Flagsmith applies all the rules, and the answer comes back ready to use. Your SDK never sees the rulebook. It only sees the final result for the identity you asked about. This is similar to calling a help desk: you describe who you are, they look up the rules, and they tell you what you are allowed to do.

sequenceDiagram
  autonumber
  participant U as End User
  participant S as Your Service
  participant K as Flagsmith SDK
  participant F as Flagsmith Edge API
  U->>S: Request arrives
  S->>K: Ask for flags for this identity
  K->>F: HTTPS call with server key, identity and traits
  F->>F: Apply overrides, segments and variants
  F-->>K: Flags and values for this identity
  K-->>S: Flag results
  S-->>U: Response shaped by the flags

Two kinds of questions

The SDK can ask two different questions. The first is “what are the flags for the environment as a whole?” The answer reflects the default settings and does not depend on any person. The second is “what are the flags for this identity, given these traits?” The answer reflects overrides, segments, and any percentage-based decisions. Most real applications use the second question, because most real decisions depend on who is asking.

Doing the maths on remote calls

Remote evaluation is wonderfully simple, but every lookup costs a network round trip. A typical call may take tens of milliseconds, and more if your servers are far from the nearest Flagsmith endpoint. That is fine for a handful of lookups. It becomes a problem at scale. Suppose a service handles 5,000 requests per second and each request checks 2 flags. If nothing is reused, that is 10,000 calls per second to Flagsmith. Over a day, that is about 864 million calls. Most of them would ask almost the same question and get almost the same answer.

Cost matters too. On a hosted plan, usage is generally measured in API requests, so remote lookups at that rate can be expensive and may hit rate limits. This is exactly why Flagsmith offers a second mode, and why high-traffic services almost always use it.

Timeouts and retries in remote mode

Remote evaluation puts a network call on your request path, so the timeout setting becomes a promise to your users. Imagine your service promises a response in one second. If the flag call is allowed to wait ten seconds, a slow Flagsmith can break that promise for every single request. Set the timeout to a small fraction of your overall budget, such as a few hundred milliseconds, and choose a default flag handler that gives safe behaviour when the timeout fires.

Retries need the same care. One quick retry can rescue a request from a momentary network glitch. Several retries, each with its own long timeout, can multiply the delay: three attempts of two seconds each means a six-second wait before the fallback even starts. A good rule is that the total time of all attempts must still fit inside the time you are willing to spend on a flag decision. When in doubt, fail fast and fall back.

Local evaluation flips the model. Instead of asking Flagsmith for answers, your service downloads the questions and the rules, and answers by itself.

When local evaluation is switched on, the SDK downloads the environment document from Flagsmith when it starts. This is one compact package describing every feature, its default state, every segment and its rules, every percentage split, and every identity override for the environment. The SDK keeps it in memory. From then on, when your code asks “what are the flags for identity 42?”, the SDK runs the shared flag engine against that in-memory document. No network call happens. The answer arrives in a tiny fraction of a millisecond.

flowchart TD
  Boot["Service starts"] --> Fetch["SDK downloads the environment document"]
  Fetch --> Mem["Document held in memory"]
  Mem --> Req["A request needs a flag"]
  Req --> Eng["Local flag engine evaluates the rules"]
  Eng --> Ans["Answer returned in microseconds"]
  Mem --> Timer["Refresh timer fires on a schedule"]
  Timer --> Fetch2["Download a fresh document"]
  Fetch2 --> Swap["Replace the old document with the new one"]
  Swap --> Mem

Staying fresh: the refresh interval

A photocopy goes out of date the moment the original changes. To handle this, the SDK runs a small background task that downloads a new copy of the document on a fixed schedule. The default is usually every 60 seconds, and you can change it. When a fresh document arrives, the SDK swaps it in as a whole, so a request in progress never sees a half-updated rulebook. In practice this means a dashboard change reaches every service within about one refresh interval plus a little caching time.

What local evaluation gives you

The honest limitations

Local evaluation is powerful, but it is not magic. Because the SDK is deciding on its own, there is no server-side identity record being consulted for each request. That has consequences you should know before you choose it.

First, traits are not saved by the decision itself. In local mode, the traits you pass are used for that one evaluation and then forgotten; they do not become stored data in Flagsmith the way they would in remote mode. If you rely on traits previously stored on an identity, you must pass them in yourself each time. Second, the document must be small enough to hold and download comfortably. Very large environments with huge numbers of segments or overrides produce bigger documents, which take more memory and time on every refresh. Third, the SDK needs a background task to keep refreshing, which is easy in a long-running web service but awkward in environments that freeze or destroy processes between requests. Finally, support for some newer features, such as identity overrides in local mode, depends on the SDK version, so check the release notes for your language.

There is no single best way to run the SDK. The right choice depends on your traffic, your runtime, and how much staleness you can tolerate.

Besides plain remote and plain local evaluation, two other arrangements deserve attention. The Edge Proxy is a small service you run inside your own network. It holds cached environment data and answers SDK requests on behalf of Flagsmith, so your services talk to something nearby and fast. It also reduces the load on the main Flagsmith API. It is distributed as a container image, so it fits neatly into existing container platforms; check the current documentation for which plans include it. The second arrangement is offline mode. Here the SDK never calls Flagsmith at all. Instead, it reads an environment document from a file you provide. This suits locked-down networks, test suites, and emergency fallbacks.

A simple way to decide

Counting the refresh traffic

Local evaluation does generate its own traffic, so it helps to do the arithmetic. If you run 1,000 service instances and each refreshes once every 60 seconds, that is 1,000 downloads per minute, or roughly 17 per second, which adds up to about 1.44 million per day. This is a tiny and predictable number compared with the billions of calls that remote evaluation could produce, and it does not grow when your user count grows. If you shorten the interval to 10 seconds, the figure becomes six times larger, so make that change deliberately.

Whether the decision happens on Flagsmith’s servers or inside your SDK, the same ordered set of rules is used. Understanding the order explains every surprising result you will ever meet.

Flagsmith checks possible answers from the most specific to the most general, and it stops at the first match. There are three layers. The most specific layer is an identity override, a value set for one exact identity. If one exists, it wins, no matter what any other rule says. If there is no override, Flagsmith looks at segments. If the identity belongs to a segment that has its own value for this feature, that value is used. When the identity belongs to several such segments, the one with the highest priority in the list wins. If no segment applies, the environment default is used, and if the feature has multivariate options, the identity is placed into one of them by percentage.

flowchart TD
  A["Flag requested for an identity"] --> B{"Identity override exists?"}
  B -- Yes --> R1["Use the identity override value"]
  B -- No --> C{"Identity matches a segment with its own value?"}
  C -- Yes --> R2["Use the value from the highest priority matching segment"]
  C -- No --> D{"Feature has multivariate options?"}
  D -- Yes --> R3["Hash the identity into a bucket and pick a variant"]
  D -- No --> R4["Use the environment default value"]

How segments find their members

A segment is a list of rules, and each rule holds conditions built from traits. A condition might say “trait country equals Germany” or “trait app_version is greater than 4.2” or “trait email contains example.com”. Rules can be combined, so that an identity must satisfy all conditions in one rule, or any one of several rules. Because the conditions read traits, the traits you pass (or have stored) decide membership. If you forget to supply a trait, a rule that depends on it simply does not match, which is a common reason why “the segment is not working”.

The magic of stable percentages

A percentage split must give the same answer to the same identity every time, otherwise nobody could trust it. Flagsmith achieves this by running a hash function on the identity combined with an identifier for the feature or segment. A hash function is a recipe that turns any piece of text into a number that looks random but is always the same for the same text. The result is turned into a position between 0 and 100. If your rollout is set to 20 percent, identities landing below 20 are in, and the rest are out.

Two lovely properties follow. First, raising the percentage from 20 to 30 keeps the original 20 percent in and only adds new people, so nobody who already saw the feature loses it. Second, because the feature or segment is mixed into the hash, the same users are not always the “first 10 percent” for every experiment, which keeps your experiments independent of each other.

Once the basics feel comfortable, the quality of your targeting depends on how thoughtfully you design the facts you send and the groups you build from them.

Designing traits like a data model

Traits are the raw material of every segment, so they deserve the same care as a database table. Choose a small, stable vocabulary and write it down. For each trait, decide its name, its type, the values it may hold, and which service is responsible for supplying it. A trait named “plan” with the values “free”, “pro”, and “enterprise” is clear and easy to target. A trait named “user_type_2” with unexplained numbers is a future headache. Keep names lower case and consistent, because a segment that looks for “Plan” will quietly fail to match a trait called “plan”.

Prefer coarse facts over precise ones. A segment rarely needs a full birth date; an age band is enough. It rarely needs an exact street address; a country or region is enough. Coarse traits are safer for privacy, smaller to move around, and more stable over time. They also make segments easier to explain to colleagues, which matters when a product manager asks why a certain customer saw a certain screen.

Building segments that stay understandable

A segment is a promise: “these are the people I mean”. If you cannot say that promise in one sentence, the segment is too complicated. “Customers on the enterprise plan in Europe” is a good promise. “People who are on plan A or B but not in region C unless their account is older than a year, except on Thursdays” is a bug waiting to happen. When a rule list grows long, split it into several smaller segments with clear names, then combine them through the priority order of the feature.

Percentages and variants without surprises

When you run an experiment with several variants, give each variant a share and make sure the shares add up as you intend. Suppose a feature offers a control value at 50 percent, variant A at 25 percent, and variant B at 25 percent. Each identity lands in exactly one bucket, and because the placement is stable, the same person sees the same version on every visit. This is important for fair measurement. If people drifted between versions, you could never tell which version caused a change in behaviour.

Be careful when you change shares during an experiment. Moving a variant from 25 to 40 percent moves some identities from one bucket to another, which can contaminate your results. If you must adjust, record the date, and analyse the periods before and after separately. For safety rollouts rather than experiments, changing percentages is normal and expected, and the stable hashing ensures that people who already have the feature keep it as the percentage climbs.

Identity choice: who is the “who”?

The identity you pass decides the unit of consistency. If you use a user ID, each person is treated individually. If you use an account or tenant ID, every user inside one company sees the same thing, which is exactly what you want for features that affect shared data, such as a new reporting engine or a changed billing screen. If you use a session ID, the same person may see different things on different visits, which is rarely wanted except for short-lived tests. Decide on purpose, and keep the choice consistent across all your services, or two services will disagree about the same customer.

Follow a single click in the dashboard all the way to a changed behaviour inside your running service, and learn where the delays hide.

Imagine an engineer turns off a misbehaving feature. Several things happen in order. The dashboard sends the change to the Flagsmith API. The API saves it to the database and writes an entry in the audit log, a permanent record of who changed what and when. It then publishes updated environment data to the fast read path, so SDKs and the Edge API see the new truth. Finally, each of your service instances picks up the new rules the next time it asks. In remote mode that is the very next lookup. In local mode it is the next scheduled refresh.

sequenceDiagram
  participant E as Engineer
  participant D as Dashboard
  participant A as Flagsmith API
  participant C as Edge Cache
  participant K as SDK Refresher
  participant S as Your Service
  E->>D: Turns the feature off
  D->>A: Save the change
  A->>A: Write to database and audit log
  A->>C: Publish updated environment data
  A-->>E: Change confirmed
  K->>C: Scheduled refresh asks for the document
  C-->>K: Fresh document
  K->>K: Swap the document in memory
  S->>K: Next flag check
  K-->>S: Feature is now off

Adding up the delay

The time between a click and a changed behaviour is the sum of a few small pieces: the time to save and publish the change (usually brief), any caching on the read path (short), and the wait until your SDK next refreshes (up to one full interval). With a 60 second interval, the worst case is a little over a minute. With a 15 second interval it is a little over fifteen seconds. If a feature is dangerous, plan your kill switch around this number, not around the moment of the click.

A word about consistency

Because each service instance refreshes on its own timer, two instances can briefly disagree. For a few seconds, instance A may already know the feature is off while instance B still thinks it is on. For many features this does not matter. For features that span several steps, such as a checkout that touches three services, it can. The safe habit is to decide once at the front door of a user journey and pass that decision along with the request, for example in a header or a field in a message, instead of letting every service decide again on its own.

The audit trail as a safety feature

Every step in the journey above leaves a trace. The audit log records who made the change, what the old and new values were, which environment it affected, and when it happened. This is more than paperwork. In an incident, it answers the most important question in the shortest time. In a review, it shows whether changes follow your process. In a regulated business, it can be the evidence an auditor asks for. Treat the log as a part of your system, not an afterthought, and learn where to find it before you need it.

Most flag-related incidents trace back to a small setting that nobody thought about. This chapter explains every important knob and what it is for.

The exact spelling of each setting varies by language, so use the official documentation for the names. The ideas, however, are universal. Here are the settings that matter most in a server-side SDK.

Create the client once

The most important lifecycle rule is that the SDK client is built once, when the process starts, and shared for the life of the process. Think of it as a long-lived helper, not a throwaway tool. In local mode, creating the client downloads the whole environment document and starts a background refresher. If you create a new client for every request, you repeat that download for every request and leave a trail of background tasks behind you. That turns a clever optimisation into an outage.

Processes, workers and runtimes

The phrase “one client per process” hides a detail that surprises many teams: how many processes does your service really run? Some web servers start several worker processes inside one container, and each worker is a separate process with its own memory. In that setup, each worker holds its own client, its own copy of the environment document, and its own refresher. If a container runs eight workers and you run fifty containers, you have four hundred clients, not fifty. Count them when you do your traffic and memory arithmetic, because refresh traffic scales with the number of clients.

Different runtimes also behave differently. A runtime built around a single event loop, such as Node.js, runs the refresher on a timer without blocking requests, but a very slow or hung download should still be protected by a timeout. A runtime with real threads, such as the Java virtual machine, typically runs the refresher in a small pool of background threads. A language that starts many short-lived processes may need an external shared cache or an Edge Proxy, because per-process downloads would repeat too often. Whatever your runtime, ask three questions: where does the client live, who refreshes it, and how does it stop?

A feature flag system must never become the reason your service goes down. Good design makes Flagsmith problems boring.

The guiding principle is called failing safe. If anything goes wrong in the flag layer, your service should continue to work with sensible default behaviour, not stop. The SDK supports this with timeouts, retries, a default flag handler, and, in local mode, the habit of keeping the last good document. The diagram below shows the order of fallbacks.

flowchart TD
  Q["Code asks for a flag"] --> M{"Local document in memory?"}
  M -- Yes --> L["Evaluate locally"]
  M -- No --> R{"Remote call succeeds within the timeout?"}
  R -- Yes --> OK["Use the answer from Flagsmith"]
  R -- No --> T{"Retries left?"}
  T -- Yes --> R
  T -- No --> DH{"Default flag handler defined?"}
  DH -- Yes --> DV["Use your safe default"]
  DH -- No --> ER["SDK raises an error"]

Designing for the worst day

Plan an actual rehearsal. In a staging environment, block the network path to Flagsmith and watch what your service does. Does it still start? Does it still answer requests? Do logs make the problem obvious? Teams that rehearse find surprising gaps, such as a health check that insisted on a fresh document and therefore killed every healthy container during a short outage, which turned a minor issue into a total one.

A small runbook for flag trouble

When something looks wrong, a short, calm checklist beats improvisation. The steps below work for most incidents involving the flag layer, and they are worth printing into your team’s runbook.

Flags sit on the hot path of your busiest code. Here is how to keep them from becoming a bottleneck as traffic grows.

Performance has two sides: latency (how long one lookup takes) and throughput (how many lookups you can handle per second). In remote mode, latency is dominated by the network. Even a well-placed service pays a small round trip, and a poorly placed one pays much more. In local mode, latency is tiny, because evaluating a handful of rules in memory is a small piece of computation. At that point your biggest costs are elsewhere, which is exactly where you want them.

Scaling the number of instances

When you add servers, each new instance performs its own initial download and its own refreshes. This is fine at normal scale, but at very large scale you may run thousands of instances. Two techniques help. First, spread out the refreshes. If every instance started at the same second and refreshes on the same schedule, they would hit Flagsmith in synchronised waves. Letting each instance start its timer from its own start-up moment naturally spreads the load. Second, put an Edge Proxy or your own cache between your fleet and Flagsmith, so thousands of instances share one upstream conversation.

Memory and the size of the document

The environment document grows with your configuration: more features, more segments, more overrides, and more rules all make it larger. A modest setup yields a small document, comfortably within memory. A very large setup, for example with hundreds of thousands of identity overrides, can be heavy to download and hold on every instance. If you reach that scale, reconsider whether identity overrides are the right tool. A segment with a rule is usually cheaper than a hundred thousand individual exceptions.

Serverless and short-lived runtimes

Functions that run on demand, such as AWS Lambda, behave differently from long-running servers. Their environment can be frozen between calls, which pauses background timers, so a refresher cannot be trusted to run on schedule. Start-up costs also matter, because a cold start that downloads a large document adds delay. For these runtimes, remote evaluation or an Edge Proxy nearby is usually the calmer choice, and offline mode with a bundled document can serve as a last-resort fallback.

A worked capacity example

Numbers make the trade-offs concrete, so let us work through one realistic example. A company runs 60 containers, each with 4 worker processes, so 240 clients in total. Each client refreshes every 30 seconds. That produces 240 downloads every 30 seconds, which is 8 downloads per second, or about 691,200 downloads per day. If the environment document is 500 kilobytes, each refresh moves about 500 kilobytes, and the fleet moves roughly 4 megabytes per second of flag data in total. That is perfectly manageable, but it is no longer a rounding error, and it shows why changing the interval from 30 to 5 seconds would multiply the load by six and deserves a careful decision.

Now compare this with the remote alternative. If the same fleet serves 20,000 requests per second and each request makes one flag lookup, remote evaluation would produce 20,000 calls per second, which is 1.7 billion calls per day. The local approach makes about 691,200 calls a day for the same fleet, which is around 2,500 times fewer calls. This single comparison explains why almost every large system ends up on local evaluation or an Edge Proxy.

A flag platform can switch features on for the whole world. Treat access to it with the same care as access to your production servers.

Security in the server-side SDK has three layers: protecting the key, protecting the data you send, and protecting the decisions the flags control. Each layer has its own simple rules.

Layer one: the key

The server-side environment key is a secret in the same family as a database password. Anyone holding it can read the full rulebook for that environment, including every segment and override. Keep it out of source code, container images, build logs, chat messages, and browser-visible files. Store it in a proper secrets service, such as AWS Secrets Manager or a similar vault, and give only the services that need it permission to read it. Create separate keys for each environment and, where possible, for each major service, so that a leak can be traced and closed without breaking everything else.

Layer two: the data you send

When you pass an identity and traits, you may be sending information about real people to a third party, or at least to another system. Use opaque identifiers, such as an internal user number, rather than email addresses or names. Send only the traits that a segment actually needs. Do not send passwords, payment details, health information, or anything that would worry you if it appeared in a log. If your privacy rules demand it, choose self-hosting or a hosted region that satisfies them, and use transient identities and traits (where your SDK supports them) so that nothing is stored.

Layer three: the decisions

A flag is only as trustworthy as the process around it. Use dashboard roles so that only the right people can change production flags. Turn on the audit log and review it after incidents. For sensitive environments, use approval workflows, where a second person must approve a change before it takes effect, if your plan includes them. Connect single sign-on so that leaving employees lose access immediately.

A short security review checklist

You cannot trust what you cannot see. A few well-chosen signals turn the flag layer from a black box into something you can reason about at three in the morning.

Start with the question every on-call engineer asks: “what changed?” Flag changes are changes to production behaviour, just like deployments. Make them visible. Flagsmith keeps an audit log, can send webhooks, and connects to tools such as Datadog and other observability or analytics platforms, so that a flag change can appear as a marker on your graphs. When a latency chart jumps, you want to see in one glance that a flag was changed two minutes earlier.

What to log, and what to leave out

Log decisions in a way that helps debugging without leaking secrets. A good log line says which flag was checked, which value came back, and which request or correlation ID it belongs to. Do not log the key. Be careful with traits, because they may contain personal facts. For a rarely seen problem, such as “why did this one customer get the old page?”, it is far easier to find the answer if your logs record the flag name, the value, and the identity label for that request.

Setting service level goals for the flag layer

Once you can see the signals, decide what “healthy” means. A service level objective is a promise you make to yourself, such as “ninety-nine point nine percent of flag lookups complete within five milliseconds” or “no instance runs for more than five minutes with a document older than three minutes”. Goals like these turn vague feelings into clear tests. They also settle arguments: if the goal is met, the flag layer is not the cause of your problem, and you can look elsewhere.

Keep the goals modest and honest. In local mode, lookups should be almost free, so the interesting goals are about freshness and fallback rates. In remote mode, the interesting goals are about latency and error rates. Review the goals after each incident, and tighten them only when the business really needs it, because every extra nine of reliability costs time and money.

The same few flag shapes appear again and again in healthy systems. The same few mistakes appear in unhealthy ones.

Patterns worth using

Patterns to avoid

Putting patterns together: a launch plan

Real launches combine several patterns. Imagine a new search ranking engine. First, the team deploys it dark, with a kill switch set to off, and runs it in the background against real traffic to compare results without showing them (dark launch). Next, a segment for internal staff turns it on, so employees use it daily (ring deployment). Then a gradual rollout takes it from 1 to 5 to 25 percent of customers, while the team watches latency and click rates. A remote config value controls how many results are re-ranked, so the team can turn the cost down during a traffic spike (operational tuning). At 100 percent, the team waits a full month, then removes the flag, the old ranking path, and the tuning value together. Each step is small, visible, and reversible, which is the whole point.

Good habits around flags matter more than clever configuration. These are the practices that experienced teams settle on.

The life of a healthy flag

Naming conventions that age well

Names are the user interface of your flags. A good name says what it controls and, when helpful, what kind of flag it is. For example, a release flag for a new checkout might be called “release_new_checkout”, an operational switch for a fragile partner might be “kill_partner_shipping_lookup”, and a plan-based feature might be “entitlement_advanced_reports”. The prefix tells the next engineer how long the flag is expected to live: release flags are short, kill switches are long, and entitlements are as long as the pricing plan. Avoid names that mention a person, a ticket number alone, or a date, because those lose meaning quickly.

A short code review checklist for flag changes

When a pull request adds or changes a flag, ask five quick questions. Is the flag name clear and unique? Is the safe default chosen on purpose? Are both the on path and the off path tested? Is the flag read once per request, instead of scattered through deep code? Is there an owner and a planned removal date? A review that takes two minutes and asks these five questions prevents most of the mistakes described in this guide.

Knowing the theory is one thing. Here is a calm, step-by-step plan for bringing the server-side SDK into a real organisation without drama.

The biggest risk in adopting feature flags is not technical. It is trying to do everything at once. Teams that introduce the SDK across fifty services in a single month often end up with inconsistent naming, forgotten keys, and nobody who owns the cleanup. A staged approach avoids this and builds confidence along the way.

Who owns what?

A successful rollout clarifies roles early. Engineers own the code that reads flags and the removal of old flags. Product managers often own the decisions about who sees a feature and when, using segments and percentages in the dashboard. Site reliability and platform teams own keys, secrets, monitoring, and the runbooks for failure. Security and compliance teams review what traits are sent and who may change production settings. When everybody knows their part, flag changes become a calm routine instead of a source of arguments.

Measuring whether it is working

Decide up front how you will know the effort is paying off. Good measures include the time it takes to turn off a faulty feature (it should fall from many minutes to under one or two), the number of emergency rollbacks that required a deployment (it should fall toward zero), the share of releases that went out dark first (it should rise), and the number of flags older than a set age (it should stay low). Review these every few months, and share the results with the wider team so the habit sticks.

Feature flags are not a fashion. Some of the best-known engineering organisations built whole ways of working around them, and one famous disaster shows what happens when flags are handled carelessly.

An illustrative setup on AWS

To bring everything together, here is a typical, illustrative arrangement for a busy API running on Amazon Web Services. It is an example of how the pieces fit, not a required recipe. Requests enter through Amazon API Gateway, pass an Application Load Balancer, and reach containers running on Amazon ECS. Each container holds one shared SDK client in local evaluation mode. The server-side key is stored in AWS Secrets Manager and given only to the task role of that service. Metrics and logs flow to Amazon CloudWatch, including document age and the default handler hit rate. The containers talk to Flagsmith Cloud, or to a self-hosted Flagsmith or Edge Proxy inside the same network.

flowchart LR
  U["End Users"] --> APIGW["Amazon API Gateway"]
  APIGW --> ALB["Application Load Balancer"]
  ALB --> T1["ECS Task 1 with SDK"]
  ALB --> T2["ECS Task 2 with SDK"]
  SM["AWS Secrets Manager"] --> T1
  SM --> T2
  T1 --> FS["Flagsmith Edge API or self-hosted Flagsmith"]
  T2 --> FS
  T1 --> CW["Amazon CloudWatch logs and metrics"]
  T2 --> CW

Short answers to the questions people ask most often when they start using the server-side SDK.

The whole story in one place: what to remember when you close this page and open your editor.

The Flagsmith server-side SDK is the bridge between a switch in a dashboard and a behaviour in your running backend. It earns its place by separating deployment from release, so you can ship code safely, release it slowly, and retreat in seconds. Everything else in this guide is detail about doing that well: choosing a mode, configuring the client, failing safely, guarding the key, and keeping the list of flags tidy.