docs / how it works

How Flagger.gg works

Agents put new work behind flags and change them through MCP, the CLI and the API, inside guardrails. People approve what goes live. Checks run in your app with no network call, and anything Flagger.gg doesn't recognize is off.

Everything on this page works today in the hosted service. Flags tied to metrics, guarded rollouts, experiments, segments and SDKs beyond Go and Node are in development. Sign up to start.

The agent loop

  1. The agent creates a flag for the work it's starting, with the MCP tool flag_create, the CLI or the API. The flag is created in every environment.
  2. It ships behind the flag. The new code path sits behind a flag check, so it can merge and deploy straight to production switched off.
  3. It reads and flips flag state to try the change on its own team, and rolls it back with the kill switch or flag_revert if something looks wrong. Every change goes through the same checks and lands in the audit log with a note.
  4. A person approves. With approvals on, turning a flag on for everyone becomes a request that someone on your team approves in the Release console. In auto-live mode the agent's change applies at once.

Declare flags in code

Your app declares the flags it uses with a key, a summary, a description and an owner, and the SDK registers them when it starts. Keys are lowercase letters, digits and underscores, starting with a letter, up to 63 characters.

const flagger = createFlagger({
  sdkKey: process.env.FLAGGER_SDK_KEY,
  defs: {
    new_billing_page: { summary: "Redesigned billing page", description: "…", owner: "payments" },
  },
});
await flagger.start();

A registered flag that doesn't exist yet is created; a flag someone already switched is never overwritten by a deploy. The console marks which flags are in code, so the code and the flag list can't quietly drift apart. A flag can also carry a "not ready" reason, which keeps it from being turned on by mistake.

States

Each flag is in exactly one of five states per environment:

StateWho sees the feature
offNo one
adminsYour admins only
targetsThe users and workspaces in the rules, plus admins
percentA sticky share of users, plus admins
onEveryone

A typical rollout moves off → admins → targets → percent → on, and then the flag is removed from the code.

Targeting rules

Rules are stored with every flag, whatever its state, so switching state never loses a target list.

  • Users: user ids, matched exactly, or emails, matched without regard to case. Only verified emails count.
  • Workspaces: workspace ids, matched against every workspace the user belongs to.
  • Percent: 0 to 100.

How percentage buckets work

For a flag in percent, take the first 4 bytes of sha256(key + ":" + userId), read them as a big-endian number, and take that modulo 100. The user is in if the result is below the percentage. The same user always lands in the same bucket for a flag, so raising the percentage only ever adds people. Both SDKs and the service run the same shared test vectors.

Checking a flag

if (flagger.flag("new_billing_page", { userId, email, isAdmin, workspaceIds })) {
  // new code path
}

In Go it's client.Enabled("new_billing_page", subject). The check is synchronous and reads an in-memory ruleset. The SDK loads the last good ruleset from disk, fetches the current one, and then follows a stream of changes, falling back to polling every 5 seconds. A check never makes a network call, and the people you check flags for are never sent to Flagger.gg.

A flag that is unknown, not yet loaded or hit an error is off. A caller with no user id only sees flags that are on.

Changing a flag

People use the Release console at app.flagger.gg. Agents and scripts use the API at api.flagger.gg/v1, the CLI or MCP, which all map to the same calls:

RequestDoes
GET …/flagsLists flags, not live first
POST …/flagsCreates a flag in every environment
PATCH …/flags/{key}Sets state and rules, with a note
POST …/flags/{key}/targetReplaces, adds or removes targets
POST …/flags/{key}/killSets the flag off and keeps its rules
POST …/flags/{key}/revertRolls back to the previous state, or to any event in its history
POST …/flags/bulkTurns several flags on in one transaction
POST …/flags/{key}/evalSays whether a flag is on for a given user, and why

A bad state, a percentage outside 0 to 100, or targets with nobody listed is rejected. Each change writes the new state, a history entry and an audit-log entry together.

Auto-live and approvals

Each project picks one of two modes:

  • Auto-live: agents' changes apply at once, and new flags start on unless they carry a "not ready" reason.
  • Approvals: new flags start off. In production an agent can target people and roll out up to a cap you set (10% by default). Turning a flag on for everyone, or rolling out past the cap, becomes a request that a person approves or declines in the Release console. Requests expire after 72 hours.

Protected flags refuse every agent change except the kill switch, in both modes.

Agents, tokens and MCP

Each agent gets its own token from the console, scoped to one project, a list of environments and the actions you choose: read, create, target, rollout, kill and request. Tokens expire after 90 days and can be revoked any time. Agents must give a note with every change, and can attach the run they're part of.

The MCP server is hosted at mcp.flagger.gg and also runs on stdio with flagger mcp. Its tools are flags_list, flag_get, flag_create, flag_set, flag_target, flag_kill, flags_bulk, flag_revert, flag_eval, requests_list and request_get. An agent only sees the tools its token allows, and there is no approve tool: approving is a person's job.

CLI

flagger login
flagger list [--not-live]
flagger get <key>
flagger create <key> --summary "..."
flagger set <key> <state> [--percent N] [--users a,b] [--workspaces x,y]
flagger target <key> [--users a,b] [--workspaces x,y] [--add|--remove]
flagger kill <key>
flagger revert <key> [--to <event id>]
flagger eval <key> --user u
flagger requests
flagger approve <id>...
flagger import --project p --env e --from flags.json

Every command takes --json. flagger login signs a person in with a device code; agents use FLAGGER_TOKEN.

Audit log

The audit log records every change across your organization: who or what made it (a person, an agent token, an admin token, an SDK registration or an import), the agent's run, when, the state and rules before and after, and the note. Filter it by project, environment, flag, agent, person or run; every filter is in the URL.

Tests

  • withFlag(key, on, fn) runs fn with the flag forced on or off.
  • setFlagOverride(key, on) forces a flag for longer, such as a whole test file.
  • bothFlagStates(key, fn) runs fn with the flag off, then on, so both code paths stay tested until the flag is removed.

Go has the same helpers in flaggertest.

Good habits

  • Off by default. A missing or unknown flag is off, so a deploy never turns on unfinished work by accident.
  • Check on the server. The server decides and enforces; the UI only hides what the server already refuses.
  • No secrets in flags. Flags hold state and targeting, never keys or tokens.
  • Remove when done. Once a feature is on for everyone and stable, delete the flag and the old code path.

More in the guides: the MCP server, setting up Claude Code, Codex and Cursor, kill switches, percentage rollouts and testing both sides of a flag.