Venom Flags
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.
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 or the REST API, 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
defaulton 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:
- Off: serve the off variation.
- Prerequisites: each listed flag must serve the named variation, or the off variation is served.
- Individual targets: a context key listed under a variation gets that variation.
- Rules, top to bottom: the first rule whose conditions all match serves its variation or its percentage rollout.
- 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 (orAlt+↑/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 aspath:linewith the line's text. References come from CI: a step posts a repository and branch's list toPOST /flags/api/v1/projects/<project>/code-refswith a Venom API key, replacing what that repository and branch had. The tab shows thecurlfor 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: use flags from your code, and change them from scripts.
- Build on Venom Flags: let Claude Code, Cursor or venom manage flags.