Documentation Index
Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt
Use this file to discover all available pages before exploring further.
Toktra gives you two complementary tools for controlling AI usage: policies for event-driven rules, and budgets for spending limits. Both are configurable from the dashboard and available via the Public API.
Policies
A policy is a rule that watches the event stream and takes an action when specific conditions are met. You define what to look for (conditions) and what to do about it (actions).
Policy conditions
Each policy has a trigger type and one or more conditions that narrow when the policy fires.
Trigger types:
| Trigger | When it fires |
|---|
| Token budget exceeded | A user or department crosses a usage threshold |
| IP risk event | GitHub integration detects a potential IP leakage event |
| Unusual usage pattern | Usage deviates significantly from a user’s baseline |
| Department threshold | A department’s aggregate usage crosses a configured limit |
Trigger: IP risk event
Conditions (AND):
risk_level = high
department_id = engineering
Policy actions
When a policy fires, it can take one or more actions:
| Action | What it does |
|---|
| Send email to user | Notifies the user whose activity triggered the policy |
| Send email to manager | Notifies the user’s manager |
| Block LLM access (hard cap) | Immediately stops the user’s LLM requests |
| Create incident | Opens a new incident in Toktra’s incident tracker |
| Webhook POST | Sends a JSON payload to a URL you configure |
Policy lifecycle
Policies are created as drafts and must be published to become active. You can test a policy against historical data before publishing — the test shows how many events in the last evaluation window would have triggered the policy. Active policies can be disabled without deleting them.
Use the test function to tune condition thresholds before publishing. A policy with overly broad conditions can generate noise that drowns out real signals.
Budgets
Budgets set limits on how many tokens — or how much money — a department or the whole organization can spend in a given period. When a budget is reached, Toktra can warn, alert, or hard-block further requests.
Department hierarchy
Budgets are organized around your department hierarchy. Departments can be nested: a parent department’s budget is the aggregate of its children. If Engineering has a budget of 10 million tokens and has sub-departments (Backend, Frontend, Data), each sub-department has its own budget that rolls up to the Engineering total.
You configure the hierarchy in Budget Management → Department Hierarchy. The dashboard shows a collapsible tree view of departments with live usage gauges.
Soft caps vs. hard caps
Each budget can be configured as a soft cap or a hard cap.
| Cap type | What happens at the limit |
|---|
| Soft cap | An alert is triggered. Requests continue. |
| Hard cap | All LLM requests from users in that department are blocked until the budget resets or an exemption is granted. |
Hard caps enforce at the agent level — the Chrome extension performs a sub-200ms preflight check before sending requests. Requests that exceed the cap are blocked before they reach the LLM provider. Ensure your team is aware before enabling hard caps on production departments.
Budget rollovers
Budgets can be configured to roll over unused tokens month-to-month. You set a rollover cap percentage — for example, 50% means that up to half of the unused monthly budget carries forward. This prevents departments from losing tokens they didn’t use without incentivizing wasteful end-of-month spending.
Rollover history is visible in Budget Management → Rollover History.
Budget exemptions
When a hard cap blocks a user who has a legitimate need, they or their manager can submit a budget exemption request through the dashboard. Exemption requests route to an admin approver. Approved exemptions temporarily raise or lift the cap for the specified user and period.
Manage exemptions at Budget Management → Exemptions.
Exemption requests are logged in the audit trail regardless of outcome. Admins can see who requested exemptions, who approved them, and for what period.
Policies vs. budgets
Both policies and budgets can trigger alerts, but they serve different purposes:
| Policies | Budgets |
|---|
| Primary purpose | Event-driven governance rules | Spending limit enforcement |
| Evaluated | In real time, per event | Continuously against cumulative totals |
| Scope | Flexible (user, department, model, risk level) | Department or org |
| Actions | Alert, block, create incident, webhook | Alert (soft cap), block (hard cap) |
| Resets | Never (stateless per evaluation) | Monthly (with optional rollover) |