Offline Mode in Flagsmith
How to keep your feature flags working when the internet is slow, blocked, or completely gone. A plain-English guide to offline handlers, environment documents, fallback layers, and the habits that keep an offline setup fresh and safe.
Picture a ship crossing the ocean. Its software has to decide, many times a minute, which features should be switched on. But the ship has no reliable internet. Or picture a factory floor whose network is sealed off from the outside world for security. Or a test machine that must give the same answer every single time, with no surprises from a faraway server.
A normal feature flag service lives on the internet, so each of these places has a problem. Offline mode in Flagsmith is the answer. It lets your application make flag decisions using a saved copy of your settings, without ever calling the Flagsmith servers. The flags still work. The rules still apply. The only thing that changes is where the settings come from.
In this guide you will learn what offline mode is, what is inside the saved copy, how decisions are made without a network, how to get fresh copies, how to layer offline mode with other safety nets, and what mistakes to avoid. Every new word is explained the first time it appears. No code is needed.
1Why Offline Mode Exists
Every network call is a small bet that the other side will answer. Offline mode is for the places where you do not want to make that bet.
The hidden assumption of most flag systems
A hosted feature flag service quietly assumes that your application can reach the internet. Most of the time that is true. But “most of the time” is not “always”. Networks drop. Firewalls block traffic. Data centres have bad days. Some environments, by design, never connect to the outside world at all.
If your application depends on a live call to fetch flags and that call fails, you need a plan. Without one, your app might crash, hang, or quietly show the wrong features. A plan for “no network” is what offline mode gives you.
Think of a printed paper map in a car. Your phone’s live map is better when the signal is strong. But when you drive through a tunnel, the paper map in the glove box still gets you home. Offline mode is the paper map for your feature flags.
Four situations where offline mode shines
Air-gapped systems
Secure networks deliberately cut off from the internet, such as some banks, hospitals, factories, and government sites. Flags must work with nothing leaving the building.
Automated tests
Tests need the same answer every run. A saved file gives exactly that, with no dependence on live settings that might change halfway through.
Disaster safety net
If the flag service is unreachable, a saved copy lets your app keep running with a known, tested set of settings.
Devices and remote sites
Machines on ships, trucks, shops, or remote sensors with slow or occasional links can still make decisions from a local copy.
What offline mode is not
Offline mode is not a way to avoid managing your flags. Someone still has to change settings in the Flagsmith dashboard, and someone still has to get the saved copy to the places that use it. Offline mode moves the decision to your side and gives you control over when new settings arrive. It is a trade: more independence in exchange for more responsibility for freshness.
Offline mode means the SDK reads settings from a saved copy that you provide, instead of calling Flagsmith over the network. Everything else about how a flag is decided stays the same.
2What Offline Mode Is, and How It Differs From Its Cousins
Several features sound similar: local evaluation, caching, default values, and offline mode. Knowing the difference saves a lot of confusion.
First, a quick reminder of two words. A flag is a named switch with an on/off state and an optional value. Evaluation is the act of working out which answer a particular user should get. Now let us place offline mode among its relatives.
| Feature | Where do settings come from? | Does it call Flagsmith? | Typical purpose |
|---|---|---|---|
| Remote evaluation | Flagsmith servers decide for you | Yes, per identity | Simple apps, browsers, phones |
| Local evaluation | SDK downloads the rulebook, then decides itself | Yes, on a timer to refresh | Fast, busy backends |
| Caching | A remembered copy of recent answers | Yes, when the copy is old | Speed and brief outages |
| Default flag handler | A fixed value your code supplies | Not applicable | Last-resort safe answer |
| Offline mode | A saved file or source you provide | No, never | No network, tests, strict isolation |
The simplest way to remember it
Local evaluation and offline mode both make decisions inside your application. The difference is where the rulebook comes from. With local evaluation, the SDK keeps downloading a fresh rulebook from Flagsmith. With offline mode, the SDK never downloads anything. You hand it a rulebook, and that is the rulebook it uses until you hand it a new one.
Local evaluation is a student who copies the latest notes from the teacher’s board every minute. Offline mode is a student who was given a printed handout on Monday and works from that handout all week. Both can answer questions without asking the teacher. Only one of them knows if the teacher changed something on Wednesday.
Offline mode and the default handler work together
The default flag handler is a fallback value used when a flag cannot be found. Offline mode does not replace it. If your saved file does not contain a flag your code asks about, the default handler still answers. Think of offline mode as the main source and the default handler as the last line of defence.
Turning on offline mode does not mean “use cached answers when the network fails”. It means “do not use the network at all”. If you want a safety net that only activates during failure, you want a fallback arrangement, which we cover in a later chapter.
3The Building Blocks of Offline Mode
Offline mode has only a handful of moving parts. Meet them one by one.
Environment document
A single structured file that describes one Flagsmith environment: its flags, values, segments, rules, and more. It is the saved copy that offline mode runs on.
Offline handler
A small piece of code or a built-in helper that knows how to fetch the environment document from somewhere local, such as a file on disk.
Offline mode setting
An SDK setting that tells it to stop calling the network and rely entirely on the handler.
Local evaluation engine
The decision logic inside the SDK. It reads the document and works out the answer for each user.
Default flag handler
A fallback that supplies a value when the document does not mention a flag.
Server-side key
The secret key used, when you do have network access, to download the environment document from Flagsmith in the first place.
A story that connects them
A team runs a warehouse system on a closed network. On a connected laptop, a build job uses the server-side key to download the environment document from Flagsmith. The file is placed inside the software package that ships to the warehouse. When the warehouse software starts, it is told to run in offline mode and given a handler that reads that file. From then on, every flag decision is made from the file, with no network calls. If a flag is missing from the file, the default handler gives a safe answer.
Think of a restaurant that prints its menu each morning. The printed menu is the environment document. The waiter who reads from it is the offline handler. The kitchen’s rule for “what do we serve when a dish is not on the printed menu” is the default handler. Nobody phones head office during dinner service.
Which SDKs support it?
Offline mode is mainly a feature of the server-side SDKs, the ones that run in your backend code. Several of them offer an offline setting and a way to plug in a handler. Client-side SDKs, which run in browsers and phones, have their own tools for working without a connection, such as storing recent flags on the device and starting with a list of default flags. Support differs from one language to the next, so always check the documentation for the SDK version you use.
4Architecture: How the Pieces Fit Together
There are two worlds in an offline setup: the connected world where documents are made, and the isolated world where they are used.
flowchart LR
ADMIN["Team member in Flagsmith Dashboard"] --> CORE["Flagsmith Core API"]
CORE --> DB[("Settings database")]
PIPE["Export job in a connected network"] -->|"server-side key"| CORE
CORE -->|"environment document"| PIPE
PIPE --> STORE["Delivery channel: image, config map, storage bucket, USB transfer"]
STORE --> FILE["Saved document on the target machine"]
subgraph ISOLATED["Isolated or offline network"]
APP["Your application"] --> SDK["Server-side SDK in offline mode"]
SDK --> HANDLER["Offline handler"]
HANDLER --> FILE
SDK --> ENGINE["Local evaluation engine"]
SDK --> DEFAULT["Default flag handler"]
end
The two worlds
On the left is the connected world. It has the Flagsmith dashboard, the Core API, and the database. It is where humans edit flags, and where an export job can fetch a fresh environment document. On the right is the offline world. It has your application, the SDK, the handler, and the saved file. There is no line from the offline world back to Flagsmith. That missing line is the entire point.
The bridge between worlds
Something must carry the document across. This is your delivery channel. It might be a build pipeline that bakes the file into a container image. It might be a configuration object mounted into a Kubernetes pod. It might be a storage bucket that an internal service reads. In the strictest cases it might even be a file copied by hand onto a secure machine. The right choice depends on how often flags change and how isolated your environment is.
Imagine a lighthouse on a rock. Supplies arrive by boat once a week. The lighthouse keeper does not phone the shore for every small question. They work from the supplies and instructions delivered last time. The boat is the delivery channel, and the weekly delivery rhythm decides how fresh the keeper’s instructions are.
Why the engine is still local
Offline mode relies on the same evaluation engine used for local evaluation. That engine knows how to apply identity overrides, segment rules, percentage splits, and multivariate options to a document. So in offline mode you keep targeting power. You can still say “premium users in Europe get the new page” and have it work, because the rules are inside the document.
Draw your own version of Figure 1 for your system, with real names for each box. Teams that can point at the export job and the delivery channel on a diagram rarely forget to monitor them.
5Inside the Environment Document
The environment document is the heart of offline mode. If you understand what is in it, you understand what offline mode can and cannot do.
What the document is
The environment document is a structured text file, in a common data format, that describes one Flagsmith environment completely enough for an SDK to make decisions on its own. Flagsmith’s Core API can produce it on request when you present a server-side key. It is the same kind of document the SDK downloads when it uses local evaluation. In offline mode, you simply supply it yourself instead of letting the SDK fetch it.
What it contains
Feature states
Every feature in the environment, with its enabled setting and value. This is the default answer for everyone.
Segments and rules
The definitions of each segment, including its rules, conditions, and operators, so the engine can test users against them.
Segment overrides
The special answers that apply to a segment, along with their priority order.
Multivariate options
The variations and percentages for any feature that splits users into versions.
Identity overrides
In recent versions, per-person overrides are included too, so the engine can honour them offline.
Environment details
Information that identifies the environment and project the document belongs to.
What it deliberately does not contain
The document is a snapshot of settings, not of live usage. It does not include the history of who evaluated what. It does not carry the traits of every user you have ever seen, because traits describe people and arrive with each request. When you evaluate in offline mode, you pass the traits for that one request, and the engine uses them for that decision only.
The environment document is like the rulebook of a board game. It lists every rule, special card, and exception. It does not list who played yesterday or what they scored. To play a round, you still need the players, who bring their own pieces to the table. In flag terms, those pieces are the identity and traits.
A snapshot has a date
Because the document is a snapshot, it is only true as of the moment it was exported. If someone changes a flag in the dashboard an hour later, your saved file does not know. This is the central reality of offline mode, and most of the design choices in the rest of this article are about living with it sensibly.
The document describes your targeting rules, your segment names, and your experiments. Anyone who can read it learns how your product is being rolled out. Store it with the same care you give to application configuration, and never ship it inside a browser or mobile app bundle.
6How a Flag Is Evaluated in Offline Mode
The reassuring news: the order of decisions is exactly the same as online. Only the source of the rulebook changes.
The same three layers
In offline mode the engine still works through the usual layers, from most specific to least specific. First it checks whether the identity has its own override. If not, it checks which segments the identity belongs to and picks the winning segment override by priority. If the feature is multivariate, it places the identity into a variation using a stable calculation. Finally, if nothing more specific applies, it returns the environment default.
sequenceDiagram
participant App as Your application
participant SDK as SDK in offline mode
participant H as Offline handler
participant F as Saved document
participant E as Local engine
App->>SDK: Start up with offline mode on
SDK->>H: Ask for the environment
H->>F: Read the saved document
F-->>H: Document contents
H-->>SDK: Environment data
SDK->>SDK: Keep it in memory
App->>SDK: Get flags for identity and traits
SDK->>E: Run the evaluation order
E-->>SDK: Winning values
SDK-->>App: Flag states, no network used
When does the file get read?
Typically the handler reads the file when the SDK starts, and the SDK holds the result in memory. After that, each flag request is answered from memory with no further file reading and, of course, no network call. That makes decisions very fast. It also means that if you replace the file on disk while the application is running, the application may not notice until it is restarted or until your code asks the SDK to reload. Check how your SDK behaves and plan your refresh method around it.
Traits and identities, offline
Identities and traits work exactly as you expect for decisions. You pass an identifier and a few traits when you ask for flags, and the engine uses them to test segment rules. What does not happen is storage. In offline mode, the traits you pass are not saved back to Flagsmith, because there is no connection to save them to. Each evaluation stands alone.
A referee with a printed rulebook makes the same rulings whether or not the stadium Wi-Fi works. The rules inside the book decide each case, and the situation on the field supplies the facts. The identity and traits are the facts. The document is the book.
Stable results for testing
Because the document is fixed, the answers are fixed. Percentage rollouts place the same identity in the same bucket every time. A test that evaluates a flag for the user “test-user-17” today will get the same answer next month, as long as the file has not changed. This is a huge advantage for automated testing, and we return to it in a later chapter.
7Offline Handlers: Where the Document Comes From
The handler answers one question for the SDK: “where do I get the environment document?” Different handlers answer in different ways.
What a handler is
A handler is a small, replaceable component that the SDK calls when it needs the environment. Because it is replaceable, you can choose or write the one that suits your setup. The SDK does not care how the document arrives, only that the handler returns it in the expected shape.
Local file handler
Reads the document from a file path on the machine. This is the most common choice and the easiest to understand. Many SDKs ship it ready to use.
Your own handler
A handler you write to fetch the document from wherever your organisation keeps it, such as an internal storage service, a secrets store, or a database.
In-memory handler
A handler that returns a document built directly inside a test, so each test can set up exactly the flags it needs with no files at all.
Choosing between them
| Situation | Best handler | Why |
|---|---|---|
| Container shipped with the document inside | Local file handler | Simple, no extra moving parts |
| Kubernetes with a mounted configuration object | Local file handler | The platform puts the file where the app expects it |
| Documents stored in an internal storage service | Custom handler | You control how and when the document is fetched |
| Unit tests for one feature | In-memory handler | Tests are self-contained and readable |
| Strictly secured server with a hand-copied file | Local file handler | Fewest assumptions about infrastructure |
A custom handler is just a promise
Writing your own handler sounds scary but is conceptually tiny. The SDK says, “give me the environment document.” Your handler fetches it from wherever you like and hands it back. That is the whole contract. The creativity is in the “wherever you like”, for example reading from an internal service that applies your company’s access rules before releasing the file.
A handler is like the delivery person who brings the morning newspaper. The reader at home does not care whether it arrives by bike, car, or a neighbour passing it over the fence. They only need the paper in their hands. You can change the delivery method without changing how the reader reads.
If your handler can fail, for example because a file is missing, decide in advance what the SDK should do. A missing file at startup is a serious problem, and it is usually better to fail loudly on startup than to quietly run with no flags.
8Getting a Fresh Document: The Export Workflow
An offline setup is only as good as its habit of renewing the document. Here is the journey from a dashboard click to a running app.
People change flags in the dashboard
Product managers and engineers edit flags, segments, and values in the connected world, as they always do.
An export job runs
A scheduled job, or a step in your release pipeline, uses the server-side key to request the environment document from Flagsmith’s Core API.
The document is checked
The job confirms the file is valid, is not empty, belongs to the right environment, and contains the flags you expect.
The document is versioned
The file gets a date, a short fingerprint called a checksum, or both, so you can always tell which copy is running where.
The document is delivered
It travels to the offline world through your delivery channel: a new container image, a configuration update, or a transfer approved for the isolated network.
The application picks it up
Either the app restarts and reads the new file, or it is asked to reload. A gradual rollout of the new document limits the blast radius of any mistake.
Someone confirms the result
A health check or log line shows the version now in use, so the team knows the change really landed.
flowchart TD
A["Flag changed in dashboard"] --> B["Export job requests environment document"]
B --> C{"Document valid and complete?"}
C -->|"No"| D["Alert the team and keep the previous document"]
C -->|"Yes"| E["Add version label and checksum"]
E --> F["Publish to delivery channel"]
F --> G["Rollout to a small group of machines"]
G --> H{"Healthy after rollout?"}
H -->|"No"| I["Roll back to the previous document"]
H -->|"Yes"| J["Roll out to all machines"]
Why the pipeline matters more than the file
Beginners often focus on the file itself. Experienced teams focus on the pipeline that produces and delivers the file. A pipeline with validation, versioning, gradual rollout, and rollback turns a risky manual task into a boring routine. And boring is exactly what you want for something that controls what your users see.
A newspaper does not just print words. It has editors who check them, a print schedule, delivery trucks, and a process for issuing a correction. The “pipeline” is the real product. The printed page is the end of a long, careful chain.
9Offline as a Safety Net: Layered Fallbacks
You do not always have to choose between “fully online” and “fully offline”. The strongest setups layer several sources, from freshest to safest.
The idea of a fallback chain
A fallback chain is an ordered list of places to look for an answer. You try the best source first. If it fails, you move to the next one. You stop at the first source that answers. For feature flags the chain often looks like this: ask the live Flagsmith service, then use recently cached answers, then use the saved offline document, and finally use the default flag handler.
flowchart TD
START["Application needs flag values"] --> L1{"Live Flagsmith reachable?"}
L1 -->|"Yes"| OK1["Use live answer"]
L1 -->|"No"| L2{"Recent cached answers available?"}
L2 -->|"Yes"| OK2["Use cached answers"]
L2 -->|"No"| L3{"Offline document loaded?"}
L3 -->|"Yes"| OK3["Use offline document"]
L3 -->|"No"| L4["Use default flag handler"]
L4 --> OK4["Safe hard-coded answer"]
How this is achieved in practice
Several SDKs let you supply an offline handler even when offline mode is turned off. In that arrangement the SDK uses the network normally, and if the network fails it uses the handler’s document as its fallback. This is a very popular design because you get live updates in normal times and a known-good copy during trouble. Whether and how this works depends on the SDK, so check its documentation before relying on it.
Freshness versus safety, layer by layer
| Layer | Freshness | Dependability | Notes |
|---|---|---|---|
| Live service | Best | Depends on the network | The normal path |
| Cache | Good, a little stale | High for short outages | Lost on restart unless stored |
| Offline document | As old as the last export | Very high | Always present if shipped with the app |
| Default handler | Never changes | Highest | Pure safe values, no rules |
Before a long flight a pilot carries live weather data, the last weather report, a printed chart, and a rule of thumb for “if all else fails”. Each is less detailed than the one before it, and each is more reliable when the radio goes silent.
Large cloud teams call this idea static stability: a system should keep doing its job using what it already has, even when the thing that normally feeds it is down. A shipped offline document gives your flags that property.
10Use Cases in Depth
Offline mode appears in more places than most people expect. Here are the most common situations, with the reasoning behind each.
Air-gapped and highly regulated environments
Some organisations forbid any outbound connection from production systems. Flag data must arrive through an approved transfer, such as an inspected file. Offline mode lets these teams use the same flag practices as everyone else, while keeping the network boundary exactly as strict as the rules require.
Automated testing and continuous integration
Tests should be repeatable and fast. If a test calls a live service, it can fail because of a slow network or because someone edited a flag in the middle of a run. A fixed document or an in-memory document makes every run identical and keeps the test suite independent of the outside world.
Local development without an account
A new engineer can clone the project and run it immediately, using a small sample document, without needing access to any Flagsmith account. This lowers the barrier to joining a project and keeps secrets off personal laptops.
Edge sites, shops, ships, and factories
Systems at the edge of a business often have flaky or expensive connections. A retail chain’s in-store software, a ship’s onboard systems, or a factory’s control software can run on a shipped document and receive a new one whenever a connection or a maintenance visit allows.
Disaster recovery and “break glass” plans
If a provider has a large outage, teams want a path that does not depend on it. A recent offline document in your own storage is a simple, cheap insurance policy that keeps flag decisions flowing while the outside world recovers.
Very fast cold starts
Some services must be ready the moment they start, such as short-lived functions or fast-scaling containers. Reading a file already present in the image avoids waiting for a network round trip before the first request can be served.
Reducing third-party dependencies in critical paths
Leaders of critical systems often ask, “what happens if every outside service is down?” Offline mode gives a clean answer for flags: they keep working from your own copy, which removes one more item from the list of things that can take you down.
11Delivery Patterns: Getting the Document Where It Is Needed
There is no single best way to deliver the file. Each approach trades simplicity against freshness.
Bake it into the image
Include the document inside the container or package at build time. It is simple and perfectly consistent, but a new document means a new build and release.
Mounted configuration
Place the document in a configuration object that the platform mounts as a file. You can update the document without rebuilding the application image.
Internal storage bucket
Keep the latest document in storage you control. A custom handler or a small sidecar program fetches it on a schedule and places it where the app can read it.
Manual approved transfer
For the most isolated networks, a person moves an inspected file across the boundary. Slow, but fits strict rules and leaves a clear audit trail.
Comparing the patterns
| Pattern | How fresh can it be? | Effort to run | Best when |
|---|---|---|---|
| Bake into image | As fresh as your last release | Very low | Flags change rarely, releases are frequent |
| Mounted configuration | Minutes to hours | Low to medium | You run on a container platform |
| Internal storage and sync | Minutes | Medium | You want near-live updates inside your own network |
| Manual transfer | Days to weeks | Highest per update | Strict isolation rules apply |
Related tools worth knowing
Flagsmith also offers a lightweight proxy that you can run inside your own network to sit between your apps and the Flagsmith service. It keeps a cached copy of the environment and serves your applications from it, which reduces calls to the outside and survives short outages. It is a different tool from offline mode, but it solves a nearby problem and is worth considering if your network allows occasional contact with Flagsmith but not constant contact. Check the current documentation for exactly what it supports.
Think of a village shop. It can get supplies by a daily truck, a weekly delivery, or by someone driving to town once a month. Daily is fresher but costs more effort. Monthly is easy but means the shelves may be out of date. The right choice depends on how fast your customers’ needs change.
Do not put a production environment document in a public code repository. Treat it like configuration, with access limited to the people and systems that need it.
12Freshness and Drift: The Central Trade-off
Offline mode trades live updates for independence. The price you pay is staleness, and the skill is to control it.
What is drift?
Drift is the growing gap between what the dashboard says and what an offline copy believes. Every minute after an export, the gap can only stay the same or get larger. If nobody refreshes the document for three months, your offline application is running three-month-old rules.
Why drift is dangerous
What drift can cause
- A feature the team turned off still showing, because the old file says on
- A fix switched on in the dashboard that never reaches the offline site
- Different machines running different documents and behaving differently
- Support confusion: “it works for them but not for me”
What controls it
- A regular, automated export schedule
- A visible version label on every deployed document
- A maximum allowed age, with an alert if a file is older
- Rollouts that update all machines within a short, known window
Choose your acceptable age
Ask a simple question for each flag: “How long can we tolerate an out-of-date answer?” A cosmetic change can wait days. A kill switch for a failing feature may need to land in minutes. If the slowest flag in your system cannot tolerate your delivery delay, you either speed up delivery or, for that flag, use a different approach, such as a separate emergency mechanism.
Keep emergency switches simple and local. A kill switch that depends on a slow document refresh is not much of a kill switch. Many teams pair offline mode with a small local setting, such as a configuration value that an operator can change on site, for the few flags that must react instantly.
A weather forecast printed on Monday is useful on Monday. By Friday it may be wrong, and nobody checking the printed copy would know. The fix is to print the date on it, so everyone can see how old it is, and to reprint it often enough that being wrong is rare.
13Client-Side Apps: Browsers and Phones Without a Connection
The environment document belongs on servers. Browsers and phones have their own, safer ways to cope with a missing network.
Why not ship the document to a phone?
The environment document holds your whole rulebook. If it were inside a mobile app, anyone who downloads the app could unpack it and read your segments, experiments, and plans. That is why offline mode with a full document is a server-side idea. Client-side SDKs use lighter tools that only ever hold the answers for one user.
Storing recent flags on the device
The SDK saves the last flags it received in the app’s storage. When the app opens without a network, it shows those saved answers straight away.
Default flags at launch
The app ships with a small list of sensible starting values. These cover the very first launch, before any flag has ever been fetched.
Preloaded state
Some setups let a server fetch flags once and hand the result to the page or app, so the client does not need its own request at startup.
Update when back online
When the connection returns, the SDK fetches fresh answers and replaces the stored ones, so the device catches up on its own.
A mobile example in words
A person opens a travel app on an aeroplane with no signal. The app has stored the flags from the last time it was online, so the new boarding-pass layout appears exactly as it did on the ground. If the app was installed fresh and never went online, it falls back to its built-in default flags, which are chosen to be safe. When the plane lands and the connection returns, the app quietly fetches current flags for that person.
A phone’s saved offline map of a city holds only the part you downloaded, not the whole world. Device storage is the same: it holds only this person’s answers, so even if the phone is lost, nobody learns your whole plan.
Never embed a server-side key or a full environment document in a mobile app or web page. Only the client-side key and per-user answers belong there.
14Performance and Scalability
Without a network, there is nothing to wait for. Offline mode is one of the fastest ways to evaluate a flag.
Why it is fast
In offline mode, a decision touches only memory inside your own process. There is no connection to open, no data to send, no server to wait for, and no reply to parse. The cost is a small amount of computing time to walk through the rules. For a busy service, that means flag checks add almost nothing to each request.
Scaling to thousands of machines
Imagine a fleet of a thousand servers. With live flag calls, every server contacts Flagsmith. With offline mode, no server does. The load on the outside world is exactly zero during normal running, and the only traffic is the occasional delivery of a new document through your own channel. That channel is usually your normal deployment system, which is already built to push files to many machines.
Memory and startup cost
The document is held in memory, so a huge environment with thousands of flags and segments uses more memory per process than a tiny one. For most teams this is small, but if you run thousands of tiny functions, each loading a big document at start, the cost can add up. Keep documents lean by deleting old flags and unused segments, and choose one environment per document rather than combining many.
Looking something up in a book already on your desk is faster than calling a library. But a very thick book takes longer to open and a bigger desk to hold. Trim the book, and the desk stays tidy.
For short-lived processes that start often, load the document once per process and share it across requests. Re-reading the file on every request throws away the speed that offline mode gives you.
15Reliability: Failure Scenarios and Recovery
Offline mode removes one big failure, a missing network. It adds a few small ones of its own. Plan for both.
| What goes wrong | What you will see | How to prepare |
|---|---|---|
| Document file is missing at startup | The SDK cannot load the environment | Fail loudly at startup or fall back to defaults deliberately; check in your deployment tests |
| Document is corrupt or cut off | Loading errors or missing flags | Validate the file in the export pipeline before delivery |
| Document is for the wrong environment | Production behaviour shows staging settings | Name and check the environment in the file before use |
| Document is very old | Features out of step with the dashboard | Alert on file age; refresh on a schedule |
| Different machines hold different versions | Inconsistent behaviour between servers | Roll out within a short window and expose the version in a health check |
| Flag asked for but not in the document | The default handler answers | Pick safe defaults and test for them |
| SDK and document format mismatch after an upgrade | Unexpected evaluation or errors | Upgrade SDKs and test with a fresh export together |
Failing safe, again
The golden rule for all flag systems applies here too: decide in advance what a flag should do when information is missing. For a risky new feature, off is safe. For a core feature, on may be safe. Write these decisions down. In offline mode there is no live service to rescue you, so the defaults and the document are all you have.
Rollback is easy if you keep history
Because the document is a file, rolling back is as simple as redeploying the previous file. Keep the last several versions, labelled and stored safely. If a new document causes trouble, restoring an older one takes seconds, not hours. This is a quiet advantage of offline mode that live systems do not offer so cleanly.
A good photographer keeps the previous version of every edit. When a change goes wrong, they simply open the older file. Keeping old documents gives you the same undo button for your flags.
16Security and Privacy
An offline setup has a small attack surface, because nothing connects out. But the file and the key still need protection.
The security checklist
- Protect the server-side key. It is the key that can download the whole environment document. Keep it in a secrets manager, use it only in the export job, and never place it on the offline machines.
- Limit who can read the document. File permissions, storage access rules, and encryption at rest all apply.
- Keep it out of public places. Never commit a production document to a public repository, a shared drive anyone can open, or a client-side bundle.
- Check integrity. Use a checksum or a signature so a machine can tell whether the file is the one your pipeline produced, and not a changed copy.
- Use least privilege. The application only needs to read the file, not write to it. Make the file read-only for the running process.
- Audit changes. Keep a record of who exported which document and when it was deployed to which machines.
Privacy: a quiet benefit
Because no traits leave your network in offline mode, you avoid sending any user information to an outside service. Traits you pass for a decision are used in memory and then forgotten. For organisations with strict privacy rules, this is a strong reason to choose offline mode. Still, think carefully about what you place in logs, since logging a user’s traits next to a flag decision can create its own privacy question.
A sealed envelope delivered by courier must arrive unopened and unchanged. The checksum is the wax seal. If the seal is broken, you know not to trust what is inside.
Ask yourself: would I be comfortable if a colleague outside the project read this file? If the answer is no, restrict who can reach it.
17Monitoring and Observability
When nothing talks to Flagsmith, Flagsmith cannot tell you what your apps are doing. You must watch your own side.
What you lose, and what to replace it with
Some Flagsmith conveniences depend on a connection. Usage analytics, which count how often flags are evaluated, are sent over the network, so in a fully offline setup they are not reported. Real-time updates are not available either. To make up for this, build your own light visibility.
Document version in use
Expose the version label or checksum of the loaded document in a health check or metrics page, so you can see which copy each machine runs.
Document age
Track how long ago the document was exported. Raise an alert when it passes your maximum allowed age.
Load success and time
Record whether the document loaded at startup and how long it took, so a broken delivery shows up immediately.
Default handler hits
Count how often the default handler answers. A rising count means the code asks for flags the document does not contain.
Flag values in logs
Log the flag values that shaped a request next to your normal logs, so a bug report can be matched to the experience the user had.
Export job health
Watch the export and delivery jobs themselves. A silent failure there means silent drift everywhere else.
A calm way to debug “why did this user get that value?”
Find the document version on that machine
Check the health information first. Many mysteries end here, because the machine is simply running an older file.
Compare with the latest export
Is that version the newest? If not, the delivery is behind.
Check the identity and traits sent
A typo, a missing trait, or a number sent as text can change which segment applies.
Walk the evaluation order
Identity override, then segment priority, then multivariate placement, then the default. The first match decides.
A lighthouse with no radio contact still keeps a logbook: what was delivered, when it arrived, and what it did that night. Your offline fleet needs the same kind of logbook, because nobody outside will see it for you.
18Testing With Offline Mode
Offline mode is one of the best things that ever happened to feature flag testing. It turns a moving target into a fixed one.
Why tests love a fixed document
A good test gives the same result every time. A test that depends on a live flag service can fail for reasons unrelated to your code: a slow network, a service hiccup, or a teammate flipping a flag. With a fixed document, or one built inside the test itself, the only thing that can change the result is your own code.
Three useful kinds of tests
Flag on and flag off
For each flag, test the code path with the flag on and again with it off. An in-memory document makes each test self-contained.
Segment behaviour
Pass traits for a premium user and a free user, and check that each gets the expected answer. This proves your rules do what you meant.
Real document check
In the pipeline, load the actual exported document and confirm that every flag your code uses is present. This catches missing flags before release.
Keep a sample document in the repository
A small, harmless sample document committed to your project, with made-up flags and segments, lets every developer run the application and its tests with no account and no secrets. Keep it separate from the real production document, and update it when your flags change in a meaningful way.
A flight simulator lets pilots practise emergencies without leaving the ground. A fixed document lets your tests practise every flag combination without touching the live system.
Test the failure path too. Start the application with the document deliberately missing, and confirm it behaves the way you decided it should, loud failure or safe defaults.
19Design Patterns and Anti-Patterns
A few shapes work well again and again. A few traps catch many teams.
Live with offline fallback
Use the network normally, and keep a shipped document as the safety net. You get fresh flags most of the time and dependable flags always.
Pipeline-owned document
One automated pipeline exports, validates, versions, and delivers the document. People never edit the file by hand.
Sample document for development
A small fake document lives in the repository so anyone can run and test the project instantly.
Version in the health check
Every machine reports which document it runs, so drift is visible at a glance.
Anti-patterns to avoid
The problem
Export the document once, ship it, and never refresh it.
Why it hurts
The document slowly becomes a fossil. Features that should be off stay on, and fixes never arrive. Nobody notices until something breaks.
Better approach
Automate exports on a schedule, add an age alert, and make the version visible on every machine.
The problem
Hand-editing the document file to “just change one value” on a live machine.
Why it hurts
The change exists only on that machine, is not recorded in the dashboard, and is lost at the next refresh. It also risks typing mistakes in a structured file.
Better approach
Change the flag in the dashboard and let the pipeline produce a new document. If you need an instant local override, design a separate, clearly named emergency setting.
The problem
Putting the full document or a server-side key inside a browser or mobile app so it “works offline”.
Why it hurts
Anyone can extract it and read all your rules, experiments, and plans.
Better approach
Keep the full document on servers. For devices, use stored per-user flags and built-in default flags.
The problem
Quietly continuing with no flags when the document fails to load.
Why it hurts
The application may run in a strange half-state, with every flag taking its default, and nobody knows why.
Better approach
Fail loudly at startup, or log a clear warning and alert, so a broken delivery is found in minutes.
20Best Practices and Common Mistakes
These habits come from teams who run isolated or resilient systems and have learned the hard way.
Habits worth building
- Automate the export. People forget; schedules do not.
- Validate before delivery. Check that the file is complete, belongs to the right environment, and contains the flags your code needs.
- Label every document. A date and a checksum make troubleshooting simple.
- Keep several old versions. Rollback should take seconds.
- Roll out gradually. Update a few machines first and check health before the rest.
- Choose safe defaults. Decide what each flag does when it is missing.
- Alert on age. A document older than your limit is a warning sign.
- Protect the key and the file. Treat both as sensitive configuration.
- Test the failure path. Practise the missing-file case before it happens for real.
Common mistakes
| Mistake | What happens | Fix |
|---|---|---|
| Assuming offline mode updates itself | Flags never change on the offline machines | Build and monitor a refresh pipeline |
| Exporting from the wrong environment | Production runs staging settings | Check the environment name inside the document |
| Committing a production document to a public repository | Your rollout plans become public | Store it in restricted storage; use a sample file in the repository |
| Forgetting a default for a new flag | Unexpected behaviour when the flag is missing | Add a default for every flag in code |
| Expecting analytics and live updates | Dashboards show no usage for offline machines | Add your own logging and metrics |
| Letting machines run different documents for weeks | Inconsistent behaviour and confusing bug reports | Show the version in a health check and roll out in a tight window |
| Re-reading the file on every request | Wasted time and disk work | Load once and keep in memory |
| Upgrading the SDK without refreshing a test document | Subtle mismatches | Test new SDK versions against a fresh export |
21Real-World Usage Patterns
The ideas behind offline mode are well known in engineering. Here is how they appear in the practices of well-known organisations.
Static stability at a cloud provider
Amazon Web Services has written publicly about static stability, the idea that a running system should keep working with the information it already has, even if the control systems that normally update it fail. A shipped flag document applies the same thinking to feature flags: the data path keeps working while the control path is away.
Graceful degradation at a streaming service
Netflix has described designing its systems to fall back to simpler, pre-prepared behaviour when a dependency is slow or unavailable, rather than failing the whole experience. An offline document and a set of safe defaults are the flag-system version of that fallback.
Reliability thinking from site reliability engineering
Google’s published site reliability engineering practice stresses reducing hard dependencies in critical paths and degrading gracefully. Keeping flag decisions inside your own process, using a copy you control, removes one outside dependency from the paths that must not fail.
Configuration delivered as files in container platforms
Container platforms such as Kubernetes commonly deliver configuration to applications as mounted files, updated without rebuilding images. Delivering an environment document the same way fits that familiar pattern and uses tools your operations team already trusts.
Retail and logistics edge sites
Businesses with many stores, depots, or vehicles often run software that must keep working through poor connections. A shipped document, refreshed whenever a connection or a maintenance window allows, lets every site behave predictably and be upgraded in controlled waves.
Deterministic test suites in continuous integration
Engineering teams across the industry use fixed configuration snapshots in tests so that builds are repeatable. An in-memory or sample document gives flag-dependent code the same repeatability.
These organisations built their own systems and published their principles. They are included to show that the ideas behind offline mode are proven engineering habits, not special tricks.
22Advantages, Disadvantages, and Trade-offs
Offline mode is a trade, and a good one when used for the right reasons.
Advantages
- Works with no network at all
- Very fast decisions made in memory
- No outside dependency in the critical path
- No user traits sent to any outside service
- Perfectly repeatable results for testing
- Easy rollback by redeploying a previous file
- Zero load on Flagsmith from your running machines
Disadvantages
- Changes do not arrive until you deliver a new document
- You must build and maintain a refresh pipeline
- Risk of drift between machines and the dashboard
- No built-in usage analytics or real-time updates while offline
- The document is sensitive and must be protected
- Mainly a server-side feature, with SDK differences to check
The big trade-offs, plainly stated
| Choice | You gain | You give up |
|---|---|---|
| Offline mode only | Total independence from the network | Live updates; you own freshness |
| Live with offline fallback | Fresh flags plus a dependable safety net | A little more setup and testing |
| Frequent document refresh | Small drift | More pipeline traffic and more rollouts to watch |
| Rare document refresh | Simplicity | Larger drift and slower fixes |
| Document baked into the image | Consistency with each release | Flag changes wait for a release |
| Document delivered separately | Flag changes without a release | One more moving part to monitor |
The right balance depends on how isolated you must be, how fast your flags need to change, and how much operational effort your team can spend.
23Frequently Asked Questions
Short answers to the questions that come up again and again.
24Summary and Key Takeaways
Key Takeaways
- Offline mode removes the network from flag decisions: the SDK reads a saved environment document through an offline handler and never calls Flagsmith.
- The decision order is unchanged: identity override, then segment override, then multivariate placement, then the environment default, all made by the local engine in memory.
- The document is a dated snapshot: it holds your rules but not live usage, so its value depends on how fresh you keep it.
- The pipeline is the real product: automate export, validation, versioning, gradual rollout, and rollback, and show the document version on every machine.
- Layer your safety nets: live service, cache, offline document, then default handler, so each failure falls to something dependable.
- Keep the full document on servers: browsers and phones use stored per-user flags and default flags, never the whole rulebook or a server-side key.
- Watch your own side: with no connection to Flagsmith, you must track document age, load success, default hits, and the health of the delivery jobs.