Budgets & FinOps Cloud

Track, allocate, and restrict LLM token costs to prevent runaway agent spend and optimize development budgets.

Why Budget Controls Matter

Agentic coding workflows can trigger thousands of parallel LLM calls, quickly generating significant API spend. Intutic's FinOps Budget Gate protects your organization from unexpected billing spikes by enforcing spend boundaries at every layer.

---

Setting Up Budget Limits

Per-Workspace Budgets

Configure spending limits from the dashboard (Settings › Billing › Budget Limits) or via environment variables:

Variable	Description
INTUTIC_BUDGET_DAILY_USD	Maximum daily spend in USD. Requests are blocked once reached
INTUTIC_BUDGET_MONTHLY_USD	Maximum monthly spend in USD

Developer Budget Tiers

Assign developers to budget tiers that match their role and usage needs:

Tier	Cap Level	Intended For
Junior	Strict	Junior engineers or experimental features
Senior	Balanced	Standard operational budget for senior engineers
Staff	High	Heavy coding sessions or complex projects
Principal	Generous	Large-scale test pipelines and architectural work

TIP

Start with conservative budgets and increase as you understand your team's usage patterns. The FinOps dashboard helps you identify trends.

---

How Enforcement Works

Each API request flowing through the proxy is checked against budget limits:

1. Cost estimation — The proxy calculates the estimated cost using model pricing data and token counting multipliers
2. Budget check — The estimated cost is compared against the developer's remaining daily/monthly budget
3. Decision — If the request would exceed the budget, it's blocked with a KILL enforcement action

Enforcement Modes & Connectivity

Intutic's budget enforcer operates in two distinct modes depending on connection status:

1. Active GKE/SaaS Enforcement (Connected Mode)

• Centralized Caps: Daily and monthly budgets are managed centrally.
• Valkey Cache Validation: The control plane caches billing limits and cumulative workspace usage counters in Valkey. The proxy performs a cache precheck (check_workspace_hard_block) — a single Valkey GET — on every incoming request.
• Heartbeat Sync: Actual query costs update Valkey counters and PostgreSQL in real time upon successful completions.

2. Local Fallback Enforcer (Standalone / Offline Mode)

• Local Budget Definition: The local proxy loads your daily budget cap (maxDailyBudgetUsd) directly from your local config (~/.intutic/config.json).
• Offline Spend Ledger: Day-accumulated spend is saved in sharded daily files (~/.intutic/logs/local-spend-YYYY-MM-DD.jsonl).
• Pre-flight Cost Interception: Before reaching the LLM provider, a native budget gate plugin estimates query cost based on prompt length and static ratios. If this would exceed the remaining budget, the proxy blocks the request with HTTP 429 Too Many Requests (OVERAGE_HARD_CAP_EXCEEDED error code).
• Offline Telemetry Ingestion: Successful completion costs are calculated, appended to the daily spend ledger, and queued in sharded files ~/.intutic/logs/traces-YYYY-MM-DD.jsonl for sync-back.

Valkey Failure Behavior (Fail-Open)

When Valkey (the in-memory cache used for budget counters) is unavailable, the budget gate fails open — requests are allowed through rather than blocked:

• Availability over enforcement: This is a conscious design decision. During a cache outage, blocking all LLM requests would halt developer productivity across the entire workspace. The budget gate prioritizes availability.
• Structured warning logs: Every request that bypasses the budget check due to Valkey unavailability emits a structured warning log entry, enabling observability dashboards and alerting pipelines to detect prolonged cache outages.
• Automatic recovery: Once Valkey is back online, the budget gate resumes normal enforcement. Spend that occurred during the outage is reconciled via the heartbeat sync process from completion events in PostgreSQL.

WARNING

During a Valkey outage, budget limits are not enforced on the fast path. Monitor your Valkey health and set up alerts for E_CACHE_UNAVAILABLE log events to minimize the enforcement gap window.

Budget Breach Anomalies

When a budget limit is exceeded, Intutic raises one of three anomaly types:

Anomaly Type	Trigger
Budget Breach	A developer or workspace has exceeded their allocated daily or monthly budget
Spawn Budget Breach	A sub-agent fleet has reached its localized budget boundary
Workflow Budget Breach	A multi-step workflow execution has exceeded its set threshold

---

Monitoring Usage

Dashboard Widgets

The dashboard surfaces budget utilization in real time:

• Budget used — on Overview, above every tab: spend against the workspace budget, as a percentage and in dollars.
• Budget Limits — on Settings › Billing: meters for Spent this month and Spent today against their caps (amber from 75%, red from 90%), the caps and alert threshold themselves, and the budget alerts raised so far.
• Cost by Virtual Key — on Overview's Cost & Token Efficiency tab: cost per virtual key, today or this month (see below).

The dashboard has no daily spend trend, per-model spend or per-developer spend view. Token Efficiency by Model on the same tab shows tokens per model, not cost.

Token Utility Classification

Every trace is classified as either:

Classification	Meaning
Useful	The agent's output was productive and valuable
Wasted	The agent looped, hallucinated, or produced unusable output

This classification feeds into the FinOps ledger and helps optimize model routing decisions over time.

---

Budget Alerts

Intutic monitors usage trends and generates alerts:

• Threshold warnings — Alerts when spending approaches budget limits (e.g., 80%, 90%)
• Breach notifications — Immediate alerts when a budget is exceeded
• Trend anomalies — Alerts for unusual spending spikes
• Forecast overruns (GA Upgrades) — Projected spend overruns warning that the 30-day forecasted spend is projected to exceed the monthly budget. Dispatched immediately to corporate Slack channels.

All budget events are logged to the budget_alerts table and appear as governance incidents in the dashboard.

---

CLI Budget Management

You can inspect your remaining budget limits and active task loops directly from your terminal:

intutic budget

This returns a clear breakdown containing:

• Cloud Budget Status: Remaining daily/monthly spend and limits from the control plane.
• Local Spending Cap: Your global daily limit configured in ~/.intutic/config.json.
• Active Task Loops: Running loops, names, accumulated costs, and localized budget limits.

---

Usage Reporting (Enterprise)

Intutic keeps an append-only cost ledger — execution_traces forbids UPDATE and DELETE at the database level — and exposes it for reporting:

• Workspace Summary: Actual cost, raw cost before routing, routing savings, input and output token totals, and call count for a daily, weekly or monthly window (/api/v1/usage/summary).
• Per-Model Breakdown: Cost and tokens grouped by requested model (/api/v1/usage/models).
• Per-Virtual-Key Breakdown: Cost and tokens grouped by which virtual key authenticated the call (/api/v1/usage/virtual-keys).
• Event-Level Detail: The individual billed calls behind those totals (/api/v1/usage/events).

Chargebacks and GL mapping are not part of the product

Cost-center GL mapping, period-end chargeback re-invoicing and the async PDF/CSV report workers were removed when the product narrowed to circuit-breaker scope, and their tables were dropped. The endpoints above are what ships.

Splitting cost by traffic class (desktop vs. app, staging vs. prod, …)

There is no dedicated "traffic class" concept — the interim answer is one virtual key per class. Mint a separate key under Settings › Security › Virtual API Keys for each class (e.g. desktop, ci, prod), point that traffic at its own key, and /api/v1/usage/virtual-keys reports each key's cost separately from that point on. The same split is on the dashboard as the Cost by Virtual Key card on Overview's Cost & Token Efficiency tab, for today or the current month. Traces from before a key existed, and any trace with no virtual-key auth context (a standalone/offline trace synced back, for instance), report under a null key — shown as unattributed on the card — rather than being folded into whichever key happens to be first.

Resolving Budget Alerts

Security and FinOps administrators can review all active budget breaches on Findings › Incidents. When resolving a breach, administrators can record:

• Resolution Status: RESOLVED status marking once action has been taken (e.g., plan tier upgraded, limits adjusted).
• Audit Trails: Record resolvedBy and resolutionNote to maintain SOC 2 compliance logs for financial audit records.

---

Related

• Settings & Configuration — Configure workspace budgets
• Core Concepts — Budget tiers and anomaly types
• Activity Logs (Traces) — Token utility classification