Agora

You're viewing the docs for Flags 0.x. The latest is 1.x (rc). Go to the 1.x (rc) docs

Console

The web console — flags, targeting, experiments, approvals, environments and operations.

node ace configure @adonis-agora/flags registers the console and publishes config/flags_dashboard.ts. It is served at /flags.

Who may open it and who is acting come from the identity provider in config/flags.ts. You can also set them here, which wins:

config/flags_dashboard.ts
import { defineConfig } from '@adonis-agora/flags/dashboard'

export default defineConfig({
  path: '/flags',
  authorize: async (ctx) => {
    if (!(await ctx.auth.check())) return { redirectTo: '/login' }
    return ctx.bouncer.allows(manageFlags)
  },
  // Who made a change, for the audit log and approvals.
  actor: (ctx) => (ctx.auth.user ? { id: String(ctx.auth.user.id), name: ctx.auth.user.email } : undefined),
})

With authkit, identity: identities.authkit() in config/flags.ts covers both.

Without authorize, the console is open outside production and answers 403 in production. With approvals on, set actor (or sign people in): two anonymous people are the same actor, and nobody can approve their own change.

What it has

  • Flags. Create flags with New flag (type, default, variants, owner, expiry, browser exposure). Search by tag, owner or staleness. Each flag shows its declared type, default and owner, and what it serves. The kill switch is one click from the list. In the editor: variants, the fallthrough (fixed or split), ordered rules, overrides, prerequisites and experiment settings (layer, holdout, metrics, guardrails, control, confidence). A context tester shows what any subject would get and why. Below that, the flag's history and its scheduled changes, including gradual rollouts.
  • Segments, layers and the global holdout.
  • Metrics. Create, edit and delete the metrics experiments use, and see which experiments use each one. Metrics from config/flags.ts are listed read-only.
  • Experiments. Exposures, the sample-ratio check, and per metric the lift, interval, p-value, sequential p-value and verdict. Guardrail alerts, and a button to recompute now.
  • Approvals. Approve, reject or cancel pending change requests.
  • Environments. Switch environments, export and import JSON, promote from one environment to another.
  • Hygiene. The stale-flag report.
  • Ops. The ruleset version and how it is kept fresh, the event transport, every sink's lag and last error, and the in-process buffer.

Filters are in the URL: copy the link to share a filtered view. /flags#/flags?env=staging&show=stale&q=checkout opens the stale flags matching "checkout" in staging, and back/forward step through your picks. The flag list (q, tag, owner, show), Approvals (status), Activity (entity, key and the page) and Hygiene (unused, static) all keep theirs there.

What the code owns

The code owns what a flag is; the console owns who gets what. A flag declared in config/flags.ts shows a defined in code lock: its type, default, variants, owner, tags and description change there, and only its targeting is edited in the console. Metrics and experiments defined in config/flags.ts show a config lock and are read-only.

A flag created in the console and declared in code later keeps the console's declaration in the ruleset, ignored. The flag shows overridden by code, with the fields where the two differ, and Remove the console declaration clears the copy; the targeting stays. A console metric with the name of a config metric shows the same way, with Delete the console metric. An experiment defined in config lists the metrics picked in the console as ignored, with Clear them.

The targeting wins over the code default: the default applies only when the ruleset has nothing for the flag. When the stored targeting serves one value to everyone and it is not the code default (usually a flag created in the console, whose targeting followed the console's default), the editor says the code default never applies and offers Return to the code default, which removes the flag from the ruleset. A kill switch is left alone.

The sidebar groups them: Flags (Flags, Segments, Layers), Experiments (Experiments, Metrics), Governance (Approvals, Activity) and Config (Environments, Hygiene, Ops). The environment picker sits in the top bar; it turns amber when you are not looking at the app's own environment. Light and dark themes are a click in the sidebar footer.

The console runs on the control-plane in a central setup; tenants have none. One console can also show other apps that keep their own flags: see Federated console.

Other consoles, search and sign-out

The console joins the app's Agora console registry. With other Agora consoles installed (durable, telescope, payments, …), the brand menu in the sidebar switches between them, showing only the ones the signed-in person may open. ⌘K (or Ctrl K) searches every one of them; here it finds flags by key or description and segments by key.

The sidebar footer shows who is signed in, a light/dark toggle and a sign-out button. The user row and sign-out work without configuration; sign-out is the one authkit announces.

Each console has its own fixed accent colour: authkit indigo #625fff, durable lime #a3e635, telescope magenta #e879f9, payments cyan #22d3ee, media amber #fbbf24, agent rose #fb7185, flags emerald #34d399 and cms orange #fb923c. The cms admin is the only console an app can rebrand (admin.theme in the @adonis-agora/cms config); accessDenied.accent colours only the refusal page. Every console has the light/dark toggle in the sidebar footer, remembered per console in each browser.

Without viewer, the footer reads ctx.auth.user once the request is already authenticated; it never triggers authentication itself. The label is fullName, name or email. Roles come from the user's role, roles and globalRoles (strings, { name } objects or authz role rows { role }) and, when authkit is installed, from the global roles of authkit's per-request identity. The footer shows one of them: the first admin-like one (a name containing admin, such as ADMIN or org_admin), else the first. A viewer(ctx) hook replaces all of this.

Set them yourself when your app differs:

config/flags_dashboard.ts
import { defineConfig } from '@adonis-agora/flags/dashboard'

export default defineConfig({
  // Who the footer shows. Return null for no user row.
  viewer: (ctx) => {
    const user = ctx.auth.user
    return user ? { label: user.fullName ?? user.email, email: user.email, role: user.role } : null
  },
  // A POST route (the form carries the CSRF token), { href: '/logout' } for a link, or false for none.
  signOut: '/logout',
})

MCP tools

With @adonis-agora/agent's mcp_provider registered, the console's tools join the app's developer MCP endpoint (/mcp/agora). Nothing to configure in this lib. Access is the console's authorize: whoever can open the console can use the tools, and nobody else sees them. To let an MCP client in with a token while people sign in as usual, combine both checks:

config/flags_dashboard.ts
import env from '#start/env'
import { anyAuthorize, authorizeByToken, defineConfig } from '@adonis-agora/flags/dashboard'

export default defineConfig({
  authorize: anyAuthorize(
    authorizeByToken({ token: env.get('CONSOLE_TOKEN') }),
    (ctx) => ctx.auth.user?.isAdmin ?? false,
  ),
})

Read tools are always listed: flags_get_overview, flags_list_flags, flags_get_flag, flags_evaluate (what a subject gets and why), flags_list_segments, flags_list_metrics, flags_list_experiments, flags_get_experiment, flags_list_change_requests, flags_list_audit, flags_list_stale and flags_get_ops.

The flags_list_* tools page like the other Agora libs' tools: pass limit (default 20, at most 100) and page, and each returns { items, next }, where next is the page to ask for next, or null on the last one.

Action tools are listed only when the app allows actions on the dev endpoint (devTools.actions in config/mcp.ts): flags_set_enabled, flags_set_rollout, flags_set_variant, flags_set_override, flags_save_flag, flags_save_segment, flags_save_metric, flags_delete_metric, flags_remove_console_declaration, flags_recompute_experiment, flags_approve_change_request and flags_reject_change_request.

Actions go through the same validation, approvals and history as the console. Where an environment needs approval, a change becomes a change request. The history records the signed-in person, or mcp:token:<fingerprint> for a token.

The console API

Everything the console does goes through JSON endpoints under <path>/api, behind the same authorize. Writes carry the x-xsrf-token header when @adonisjs/shield sets the XSRF-TOKEN cookie. Every endpoint takes ?environment= (or environment in the body).

RequestBodyDoes
GET /api/flags{ data }: flags, declarations and what each serves
POST /api/flags{ key, declaration }Create a flag
PUT /api/flags/:key{ definition, note? }Replace a flag's targeting
DELETE /api/flags/:key/declarationDrop the console declaration of a flag the code now declares (409 for a flag only the console declares)
POST /api/flags/:key/enabled{ enabled }The kill switch: false serves offVariant to everyone; true lifts it, back to the targeting
POST /api/flags/:key/rollout{ percent }Percentage rollout of an on/off flag
POST /api/flags/:key/variant{ variant }Serve one variant to everyone
GET /api/metrics{ data }: config and console metrics, and the experiments using each
PUT /api/metrics/:key{ metric, note? }Create or replace a console metric (409 for one defined in config)
DELETE /api/metrics/:keyDelete a console metric (422 while an experiment uses it), or the console copy of a metric config defines (409 when there is none)
GET /api/auditThe change history, newest first (paged, see below)
GET /api/change-requestsChange requests, newest first (paged)
GET /api/schedulesScheduled changes, soonest first (paged)
GET /api/consolesThe other Agora consoles the signed-in person may open
GET /api/consoles/search?q=Search across those consoles and this one

The catalogs (/api/flags, /api/segments, /api/layers, /api/metrics, /api/experiments, /api/stale) return the whole environment as { data, … }.

The history, change requests and schedules speak the filter list format: filter[field]=value to narrow, first for the page size, and { data, meta: { nextCursor, prevCursor, hasNext, hasPrev } } back. An unknown filter field, a value it does not accept, or a sort other than the list's own order answers 400.

ListFiltersOrderfirst
GET /api/auditentity (flag, segment, layer, metric, holdout, ruleset), key-atdefault 50, at most 200
GET /api/change-requestsstatus (pending, approved, rejected, applied, cancelled); none: every status-requestedAtdefault 100, at most 500
GET /api/schedulesflag, status (pending, running, done, failed, cancelled)runAtdefault 100, at most 500

The history pages forward: send meta.nextCursor back as after for older changes.

app/services/flag_history.ts
import { filterQuery, type CursorPageResponse } from '@adonis-agora/filter-client'

const query = filterQuery().where('entity', 'flag').where('key', 'new_checkout').first(50)
const page: CursorPageResponse<AuditEntry> = await fetch(
  `/flags/api/audit?${query.toQueryString()}`,
).then((r) => r.json())

if (page.meta.nextCursor) query.after(page.meta.nextCursor) // the next, older page

Change requests and schedules answer one page: meta.hasNext says more match than first, so narrow the filter or raise first.

enabled: true does not turn a flag on: on a flag that was never configured, the targeting created for it still serves the default. Use variant (on) or a rollout.

A definition:

{
  "variants": { "classic": "classic", "one_page": "one_page" },
  "enabled": true,
  "offVariant": "classic",
  "rules": [
    {
      "id": "pro",
      "conditions": [{ "attribute": "plan", "op": "in", "values": ["pro"] }],
      "serve": { "variant": "one_page" }
    }
  ],
  "fallthrough": { "split": [{ "variant": "classic", "weight": 1 }, { "variant": "one_page", "weight": 1 }] },
  "experiment": {}
}

fallthrough is { "variant": … } or { "split": [...] }; Targeting lists the operators, segments, overrides and prerequisites. A change that needs approval answers 202 with the pending request.

On this page

Partner

Your product as the official integration for Flags, right here.

Become a partner →