---
title: Venom Flags
description: Put features behind flags in Venom Cloud, target users and segments, roll out by percentage per environment, review every change before it saves, and revert anything from the history.
section: cloud
order: 140
audience: [user, operator]
sources: ["services/nodejs-cloud/app/(flags)", services/nodejs-cloud/components/flags, services/nodejs-cloud/lib/flags/contract.ts, services/nodejs-cloud/lib/flags/eval.ts, docs/adr/0053-venom-flags.md]
features: [cloud.page-flags]
---

Venom Flags is the feature flag service inside Venom Cloud, at `/flags`. You wrap new code in a flag, decide per
environment who gets it, and change that without a deploy. Agents work the same flags people do: everything the app
does, an agent can do over the [MCP server](/docs/developers/flags.md) or the [REST API](/docs/cloud/flags-sdk.md), and every change, from
anyone, lands in one history you can revert from.

Flags is an add-on, like Venom Notes and Venom Tasks. An owner or a billing member adds it on the billing page; until
then `/flags` says so. On the app rail it is the flag icon; `g f` opens it from any app, and ⌘K finds flags by key,
name or tag (type `flags:` to search only flags).

## How it fits together

- A **project** holds your flags and its **environments**. Every org gets a project called `default` on first use,
  with three environments: Production (red), Staging (amber) and Development (green). Switch projects with the
  project menu in the top bar (or `?project=<key>` on any page). Admins add one there with **New project…**: a name
  (the key is made from it), a description, then the new project's SDK keys for each environment, shown in full this
  once with copy buttons.
- A **flag** has a key (what your code asks for), a name, a kind (boolean, string, number or JSON), its
  **variations** (the values it can serve), tags, a maintainer, and whether it is temporary (a release toggle you
  expect to remove) or permanent (a kill switch, an entitlement).
- Each environment has its own **targeting** for the flag: on or off, prerequisites, individual targets, rules, a
  default rule and the variation served while off. Turning a flag on in Staging never touches Production.
- A **segment** is a reusable group of contexts (users, orgs, devices or any kind you send) in one environment:
  keys included, keys excluded, then rules.

Your SDK asks "what does this context get for this flag?" The answer is worked out in this order:

1. Off: serve the off variation.
2. Prerequisites: each listed flag must serve the named variation, or the off variation is served.
3. Individual targets: a context key listed under a variation gets that variation.
4. Rules, top to bottom: the first rule whose conditions all match serves its variation or its percentage rollout.
5. The default rule (fallthrough): one variation, or a rollout.

A **percentage rollout** hashes the context's key (or any attribute you pick to bucket by, such as `org.key`) with the
flag's salt, so the same context always lands in the same bucket and moving from 10% to 20% keeps the first 10%.

## Pages

| Page | Path | What it is for |
|---|---|---|
| Flags | `/flags` | every flag in the project, with its state in the environment you pick |
| A flag | `/flags/f/<key>` | its targeting per environment, variations, insights, scheduled changes, code references and history |
| Stale flags | `/flags/stale` | flags that may be ready to remove, per environment, with one-click archive |
| Segments | `/flags/segments` | segments per environment; one opens at `/flags/segments/<env>/<key>` |
| History | `/flags/history` | every change in the project, with who made it and from where |
| Settings | `/flags/settings` | environments, SDK keys and webhooks |
| Connect an agent | `/flags/agents` | a link to the Connect page (`/connect`) and to the Flags-only endpoint, and the agents' recent changes |
| Quickstart | `/flags/quickstart` | the TypeScript SDK and `curl` examples with this project's names filled in |

## The list

The list shows each flag's name, key, kind, tags, maintainer and whether it is on in the environment you picked. The
environment switcher shows each environment in its colour, and the app remembers the last one you used.

- **Search** with `/`: it matches key, name, description and tags.
- **Filter** by tag, environment state (on or off), status (active, archived or all), maintainer and kind. Filters
  live in the URL, so a filtered list is a link you can share.
- **Toggle** a flag in the current environment with its switch or `t`. In an environment with "Confirm changes" on
  (Production, by default), the app asks first.

| Key | Does |
|---|---|
| `/` | search |
| `j` / `k` | next / previous flag |
| `Enter` | open the flag |
| `t` | turn the focused flag on or off here |
| `c` | new flag |
| `⌘S` / `Ctrl+S` | on a flag's page: review and save the pending changes |
| `Esc` | on a flag's page with nothing pending: back to the list |
| `Shift+S` / `Shift+H` | Segments / History |
| `g f` | open Flags from any app |

**New flag** (`c`, or ⌘K → New flag) asks for a name (the key is made from it, and you can edit it), the kind, the
variations (On and Off for a boolean), tags, and whether it is temporary. A new flag is off everywhere.

## A flag's page

The header shows the name, the key with a copy button, the kind, tags, maintainer and a Temporary badge. Its
buttons archive a flag (it disappears from lists but keeps serving as configured), restore it, or delete it,
which asks you to type the key.

Environment tabs, in each environment's colour, switch the targeting below.

### Targeting

- **On / off** for this environment.
- **Prerequisites:** other flags that must serve a given variation first.
- **Individual targets:** context keys as chips under each variation, grouped by context kind.
- **Rules:** each rule has conditions and what it serves. A condition picks a context kind, an attribute, an operator
  and values (chips), and can be negated. Operators: is one of, starts with, ends with, contains, matches regex,
  `<`, `≤`, `>`, `≥` (numbers), is before / is after (dates), semver `=`, `<`, `>`, and is in segment. A rule serves
  one variation or a rollout: sliders per variation that always add up to 100%, plus the attribute to bucket by.
  Move rules with the arrows (or `Alt+↑` / `Alt+↓`); order matters, the first match wins.
- **Default rule:** what everyone else gets.
- **Off variation:** what is served while the flag is off.

Edits are a draft. A bar at the bottom, **Review and save**, shows each pending change in words ("Turn on in
production", "Add a rule (2 conditions) in staging") and the field-by-field diff the server worked out, and takes an
optional comment. Saving sends the change with the version you opened. If someone, or an agent, changed the flag in
the meantime, the save is refused with "changed since you opened it — reload": reload to see the latest, then make
your change again. **Discard** drops the draft. The bar also names anything the server would refuse (a condition
with no values, a rollout that doesn't add up to 100%) before you try.

If the environment needs approval, saving creates an approval request instead, and the change applies once someone
approves it: requests waiting show at the top of **History**, with Approve (which applies the change) and
Reject.

### Variations, insights and history

- **Variations:** each variation's value, name and description. Values are checked against the flag's kind.
  Removing a variation is its own change (targeting refers to variations by position), so it asks first.
- **Settings:** name, description, tags, maintainer, temporary or permanent, and client-side availability.
- **Insights:** evaluations per hour, stacked by variation, from the counts your SDKs send, and when the flag was last
  evaluated.
- **History:** every change to the flag: who made it, a "via agent" badge with the agent's name when an agent did,
  the comment, and the diff (click to expand). **Revert** restores the flag as it was before that change, as a new
  change in the history. If the flag has changed since, the app says so and asks before reverting anyway.

### Schedule and code

- **Schedule** (`?tab=schedule`): changes that apply later, such as turning a flag on at launch time or stepping a
  rollout up overnight. Pick the environment, a date and time (in your browser's time zone, which the form names),
  and the change: turn it on, turn it off, a percentage rollout on the default rule, or one variation for everyone.
  The form shows the change in words before you schedule it. The server checks it at once and applies it at the time,
  as you, with your comment in the history ("via schedule"); it runs within a minute of the time. The list shows each
  change as pending, done, failed (with the reason) or canceled, and a pending one can be canceled.
- **Code** (`?tab=code`): where your code reads the flag, grouped by repository and branch, each as `path:line` with
  the line's text. References come from CI: a step posts a repository and branch's list to
  `POST /flags/api/v1/projects/<project>/code-refs` with a Venom API key, replacing what that repository and branch
  had. The tab shows the `curl` for it when nothing has been sent yet.

### Test a context

Paste a context, such as `{"kind": "user", "key": "u-1", "plan": "pro"}` or a multi-kind context
`{"kind": "multi", "user": {"key": "u-1"}, "org": {"key": "acme"}}`, to see what the saved flag serves it in the environment you pick, and why
(off, target match, rule 2, default rule, prerequisite failed). Nothing is counted.

## Stale flags

`/flags/stale` lists the active flags in one environment that may be ready to remove, over a window of 30, 60 or 90
days. Each shows why: never evaluated, not evaluated within the window, serving only one variation, an old temporary
flag, or safe to archive (not evaluated, no code references, and older than the window). It also shows when the flag
was last evaluated, its age and how many code references it has. **Archive** archives it at once, with Undo in the
confirmation; archived flags keep serving what they serve now, and every archive is in History.

## Segments

`/flags/segments` lists each environment's segments. A segment's page shows included and excluded keys as chips
(per context kind) and its rules. Excluded keys win over rules; included keys win over everything. A flag's rule uses
a segment with the "is in segment" operator.

## Settings

Admins (owners and admins) manage the project here:

- **Environments:** name, colour, order, **Require approval** (changes there become approval requests; off by
  default, so agents act alone) and **Confirm changes** (the app asks before a toggle; on for Production).
- **SDK keys:** each environment has a server-side SDK key (`vfs_…`), a mobile key (`vfm_…`) and a public
  client-side id (`vfc_…`). Keys are shown in full once, when created or rotated; afterwards only their first
  characters. Rotating a key stops the old one at once.
- **Webhooks:** URLs that receive a signed POST after each change (all resource kinds, or the ones you pick). The
  signing secret is shown once.

The org's own webhooks (Settings → Webhooks, for every product) also carry `flags.flag.created`, `flags.flag.updated`
and `flags.flag.deleted`, sent once the change is saved: the project, key, version, whether the flag is on in each
environment, the paths that changed and who. The changed values are left out, since a target list can name users.

## Who can do what

| Role | Read | Change flags and segments | Environments, SDK keys, webhooks |
|---|---|---|---|
| Owner, admin | yes | yes | yes |
| Developer | yes | yes | no |
| Billing, viewer | yes | no | no |

## Related

- [Venom Flags SDK and REST API](/docs/cloud/flags-sdk.md): use flags from your code, and change them from scripts.
- [Build on Venom Flags](/docs/developers/flags.md): let Claude Code, Cursor or venom manage flags.
