Getting Started
Overview
Understand FlagForge and how operators and application developers use it to manage and evaluate feature flags
Overview
FlagForge is a self-hostable feature-flag and remote-config platform for teams that want to control flag management and evaluation in their own environment. Operators run its Fastify REST control plane to manage projects, environments, typed flags, segments, targeting, and rollouts. Node.js developers use the TypeScript SDK to bootstrap configuration and evaluate flags locally in their applications.
Key features
Run the FlagForge API in your environment and retain control of flag configuration and operational data.
Manage boolean, string, number, and JSON flags with named variations for feature gates and application settings.
Serve variations by user attributes and reusable segments, or release a change gradually with percentage rollouts.
Bootstrap definitions once with the SDK, then evaluate flags in process without a network request for each check.
Use webhooks for flag lifecycle notifications and audit logs with before-and-after snapshots of changes.
Explore the live REST contract through the API's Swagger UI at /docs or its OpenAPI JSON at /openapi.json.
How it works
Run the control plane
Self-host the FlagForge API and connect it to its database. The service listens on port 4000 by default and exposes a liveness endpoint at http://localhost:4000/health.
Organize your configuration
Create a project and its environments, then define typed flags and named variations. Configure each environment independently so development and production can use different targeting and defaults.
Set targeting and rollout rules
Use evaluation contexts, segments, conditions, and percentage rollouts to decide which variation a user receives. Management requests use a server key; keep this credential in operator or backend systems.
Bootstrap your application
Install @flagforge/sdk and construct FlagForgeClient with a client key, the API base URL, and an environment key. Calling await client.init() fetches definitions from GET /v1/config.
Evaluate locally and refresh when needed
Call isEnabled, getString, getNumber, getJson, or variation with an evaluation context. The SDK evaluates against its bootstrapped definitions locally; you can refresh manually or configure background polling and change listeners.
Supported surfaces
| Surface | Use it for |
|---|---|
| Fastify REST API | Self-hosting the control plane, managing projects and environments, configuring flags and segments, and performing server-side evaluation. |
| TypeScript SDK for Node.js | Bootstrapping flag definitions and evaluating boolean, string, number, and JSON values in a Node.js application. |
| Pure TypeScript core engine | Reusing evaluateFlag or evaluateAll with flag definitions and an evaluation context when you need the shared evaluation semantics outside the hosted API. |
| REST clients and OpenAPI tools | Calling management and evaluation endpoints with Bearer server or client API keys, and discovering request shapes from /docs or /openapi.json. |
Note:
Use server keys for control-plane management and client keys for evaluation and SDK bootstrap. Treat server keys as secrets; client keys are intended for application evaluation access.