AdminGovernanceOps

Admin & Governance Guide

A practical operating guide for administrators: budgets, policies, usage, auditability, and incident response with request-id correlation.

Open UsageOpen Org Settings
Recommended screen flow
Login → Org → Workstream → Mission → Run → Outcome → Policy Trace → Usage
Operators work left-to-right: navigation (left), execution (center), evidence (right).
Key governance controls
  • Daily USD budget
  • Daily token budget
  • Allowed model allowlist
  • PII egress allowlist
Operational endpoints
/healthzprocess up
/readyzdeps ready
/docsAPI console
/openapi.jsonspec

1) Roles and responsibilities

Owner / Admin
  • Set budgets and allowlists
  • Manage API keys
  • Review policy traces and audit logs
  • Respond to incidents
Member
  • Create missions
  • Run workflows within budgets
  • Produce outcomes and exports
Viewer
  • Read-only access
  • Audit review and evidence inspection

2) Configure budgets and model allowlists

Go to Org Settings and configure:
Daily cost cap (USD)
Hard limit. Requests are denied when the day’s total reaches the cap.
Daily token cap
Hard limit across input + output tokens for the org (UTC day).
Allowed models
Allowlist models permitted for this org (e.g., gpt-4.1, gpt-4o-mini).
PII allowed providers
Restrict which providers may receive PII. Use this for regulated environments.
Recommended: start conservative.

Example org_settings (settings JSONB):
{
  "max_cost_usd": 25,
  "max_tokens_day": 250000,
  "allowed_models": ["gpt-4o-mini", "gpt-4.1-mini"],
  "pii_allowed_providers": ["openai"]
}
Metering uses model pricing when configured; otherwise a conservative default cost-per-1k heuristic is used.

3) Understand policy trace and denials

Every governed request produces a Policy Decision. In the Outcome modal, open Policy Trace.
  • Allowed: policy checks passed; execution proceeded.
  • Denied: a policy check failed; request blocked before execution.
  • Policy decisions include the request id for correlation.
Common denial reasons:
- model not in allowlist
- daily cost cap exceeded
- daily token cap exceeded
- PII egress restricted (when enabled)

4) Usage and budgets (how to interpret)

Open Usage & Budgets to view real-time totals for the current day.
Cost used today
Sum of metered requests for 2026-01-21 (UTC day).
Tokens used today
Input + output tokens across chat, RAG and optimization endpoints.
If you hit budget caps: increase caps, narrow model allowlist, or reduce high-frequency workflows.

5) Incident response with request-id correlation

When users report an issue, capture the Request ID shown in error banners/toasts (or from the policy trace).
Triage flow:
1) Ask for Request ID
2) Search gateway logs for that request id (x-request-id)
3) Inspect policy decision record (allowed/denied + reasons)
4) Validate org settings at time of event
5) Check /readyz for dependency health
Suggested operator actions:
  • Denied by budget: raise cap or pause high-volume missions
  • Denied by allowlist: add model to allowlist or switch default model in UI
  • Repeated failures: check Supabase status, gateway env vars, and rate limiting

6) Operational checklist (production)

  • Verify /healthz returns 200
  • Verify /readyz returns 200 (Supabase reachable)
  • Ensure budgets + allowlists are set for each org
  • Confirm policy decisions are being recorded for governed endpoints
  • Confirm Usage totals reflect expected activity
For regulated workloads, enable strict allowlists and restrict PII provider egress.
Admin Guide • Print-friendly • Designed for operational handoff
User guideUsageSettings