Quickstart

FlagDrop runs differently from every other feature flag service: we push signed JSON to your bucket and your SDKs read locally. This guide takes you from nothing to a flag in production in under four minutes.

#Install

FlagDrop ships SDKs for Node, Python, Go, Rust, Swift, Kotlin, and edge runtimes. Pick yours:

# node / deno / bun
$ npm i @flagdrop/sdk

# python 3.10+
$ pip install flagdrop

# go
$ go get github.com/flagdrop/go

# rust
$ cargo add flagdrop

#Connect your bucket

FlagDrop needs one-time write access to a bucket you own. We recommend a dedicated bucket per project. Grant access via the dashboard — we never receive your access key.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid":      "FlagDropWrite",
    "Effect":   "Allow",
    "Action":   ["s3:PutObject", "s3:GetObject"],
    "Resource": "arn:aws:s3:::acme-flags-prod/*"
  }]
}

#Create your first flag

Create a flag from the dashboard, the CLI, or your coding agent via MCP. All three paths write the same signed config.

$ flagdrop flag create new-checkout \
    --type bool \
    --default false \
    --env production

→ created flag 'new-checkout' (bool)
→ pushed to s3://acme-flags-prod/production.json
→ signed with project key ...7f3a
✓ ready · 0.8s

#Read it in code

Every SDK is five lines or fewer. Initialize the client, wait for the first sync, then call a typed getter.

import { FlagClient } from '@flagdrop/sdk'

const flags = new FlagClient({
  bucket:      'acme-flags-prod',
  environment: 'production',
  refreshMs:   5000,
})

await flags.ready()

if (flags.getBool('new-checkout', false)) {
  renderNewCheckout()
}

That's it. Your SDK is now hot-reloading from your bucket every refreshMs. Median eval: 0.3ms. No network hop per call.

Architecture

FlagDrop splits the system into a control plane (us) and a data plane (you). We push; you read. Nothing in your request path ever talks to our servers.

  ┌──────────────────┐        push()         ┌─────────────────┐        read()         ┌──────────────┐
  │  flagdrop cloud  │ ────signed manifest──▶ │  your bucket    │ ◀──hot-reload, 5s──── │  your SDKs   │
  │  dashboard / mcp │                        │  s3 · gcs · r2  │                       │  in-process  │
  └──────────────────┘                        └─────────────────┘                       └──────────────┘
         ▲                                                                                      │
         └──────────────────────── audit log ◀──────── eval metrics (opt-in) ────────────────────┘

#Flags & types

A flag is a named, typed value. FlagDrop supports four primitives and one compound:

• bool — boolean toggle, the most common case.
• string — useful for variant tags like 'control' | 'v2' | 'v3'.
• number — percentages, thresholds, feature limits.
• json<T> — arbitrary typed object. Validated by schema if provided.
• variant — weighted multi-value with deterministic bucketing by user.

#Targeting rules

Rules are a transparent JSON AST. You can diff them in Git, render them in PRs, and let an agent reason about them:

{
  "if": { "and": [
    { "eq": ["user.plan", "pro"] },
    { "in": ["user.country", ["US", "CA", "UK"]] },
    { "lt": [{ "hash": "user.id" }, 0.25] }
  ] },
  "then": true,
  "else": false
}

#Rollouts

Every flag supports a rollout percentage from 0-100 with stable per-user bucketing. Combine with targeting to ramp a cohort. Schedule auto-promotions with cron syntax. Kill-switch revokes a flag across all SDKs in under 5 seconds — one write to your bucket.

FlagClient

The FlagClient is the single entry point for every SDK. It maintains a local cache of your flag config and refreshes from your bucket on a configurable interval.

Constructor

ClientConfig

#Methods

ready()

Resolves after the first successful bucket sync. Safe to call multiple times.

getBool()

Synchronous boolean read. Never throws; returns the default if the flag is missing.

getString() / getNumber() / getJson()

getVariant()

Deterministic bucketing by context.userId across SDKs. Same input, same output, every runtime.

on(event, handler)

Subscribe to config updates or transport errors. Returns an unsubscribe function.

#Errors

FlagDrop getters never throw. Transport errors are surfaced via the 'error' event and the client keeps serving the last good config.

#MCP tools

When the FlagDrop MCP server is connected, your coding agent gets six tools scoped to your project. Permissions are bounded per-agent via API key scopes.

CLI

The flagdrop CLI is a thin wrapper around the same REST API the dashboard uses. Install with npm i -g @flagdrop/cli or brew install flagdrop.

USAGE
  flagdrop <command> [options]

COMMANDS
  init            scaffold a project in the current repo
  flag create     create a new flag
  flag toggle     flip a boolean flag
  rollout         set rollout percentage
  kill            revoke a flag across all SDKs
  push            push current config to bucket
  estimate        show what you'd pay vs competitors
  audit           read audit log

#Migrations

We wrote importers for LaunchDarkly, Split, and Statsig. Run flagdrop migrate <vendor>, paste your export token, and FlagDrop will re-create every flag, rule, and segment in your bucket. Pro and Enterprise customers get a free pairing session — usually done in under a day for ≤500 flags.

#Self-host

Enterprise customers can run the FlagDrop control plane inside their own VPC via our Helm chart. SDK and config format are already open-source under Apache-2.0.

$ helm repo add flagdrop https://charts.flagdrop.io
$ helm install fd flagdrop/control-plane \
    -n flagdrop --create-namespace \
    -f values.yaml

Changelog

Every shipped version of FlagDrop, newest first. Subscribe via RSS at /changelog.rss.