Operations & plans

Everything on this page is already enforced in the local and self-hosted builds — the plan tier is just a field on the workspace. Wiring up a billing provider changes who may switch plans, not what the enforcement layer does.

Plans & run quotas

Every run-trigger surface — manual, webhook, MCP, and the scheduler — counts against a single monthly quota set by the workspace plan:

The quota window is the calendar month in UTC, resetting at 00:00 on the 1st. It counts every run created in the current month regardless of final status — a failed or cancelled run still consumes quota, because the work was attempted. The check runs before graph validation, so a workspace at its limit is refused even for a valid workflow.

At the limit, triggers return 402 Payment Required with a plain, itemised explanation — no runs are silently dropped:

HTTP/1.1 402 Payment Required
{
  "detail": "Monthly run limit reached (1,000/1,000 on the free plan) — upgrade the workspace plan to keep running"
}

Behaviour per trigger surface

Managing the plan

{ "plan": "pro" }
// →
{ "id": "0af31c92bd07", "name": "Acme", "plan": "pro", "member_count": 5, "created_at": "2026-06-01T00:00:00Z" }

Budgets & cost enforcement

Quotas cap the number of runs; block budgets cap the dollars. A budget is now enforced on every trigger surface — manual POST /api/workflows/{id}/runs, replay, webhook, schedule, and MCP — so no path can quietly spend past the cap. A trigger that would exceed the budget is refused with 402 Payment Required and never queued.

Atomic reservations

A budget can carry a per-run reservation_estimate_usd. On each trigger the engine places a hold for that amount under a per-budget row lock, so concurrent triggers cannot race past the limit — at the boundary exactly one of N simultaneous triggers is admitted and the rest get 402. Each hold settles to the run's actual spend when it finishes, so an overestimate is released rather than lost.

Budget status reports the full ledger, so a dashboard can show headroom before a run is even created:

Override with approval

A run that failed on budget can be resumed past the cap, but only by an admin — the authorization is the approval, and the act is fully audited.

{ "approved": true, "cap_usd": 5.00, "reason": "One-off backfill approved by finance" }

Data retention

A background sweeper runs at startup and every 24 hours thereafter, deleting execution and audit data older than the plan window. Deleting a run cascades to its steps and checkpoints. A sweep that removes anything logs an audit entry (retention_sweep on the workspace) whose details are the counts it removed; a sweep that removes nothing is silent.

Windows are measured from each record's creation time. Runs and the audit log have independent windows, which is why an audit trail can outlive the runs it describes on the pro plan.

Failure & approval alerts

When a run fails or pauses at a human gate, the backend notifies your team. Delivery is entirely env-gated — unset means silent, so local development stays quiet. Slack and email fire independently: you can enable either, both, or neither.

Two events trigger an alert. A failedevent carries the run's error message; a paused event carries the human-gate prompt.

[Ballast] Run af772b3602ef of 'Support Triage Crew' failed: Node 'Fetch CRM' failed: tool 'crm' returned HTTP 500
[Ballast] Run b91c04d2ee01 of 'Support Triage Crew' is paused at a human gate: Review the drafted support reply before it is sent.

Subject: [Ballast] Run failed — Support Triage Crew
Body:    Run af772b3602ef of 'Support Triage Crew' failed: Node 'Fetch CRM' failed: tool 'crm' returned HTTP 500

Subject: [Ballast] Approval needed — Support Triage Crew
Body:    Run b91c04d2ee01 of 'Support Triage Crew' is paused at a human gate: Review the drafted support reply before it is sent.

• Alerts are fire-and-forget: the executor schedules them without awaiting, and any delivery problem is logged and never affects the run itself
• The email body is the same one-line text as the Slack message, minus the [Ballast] prefix that only Slack carries
• Member invites reuse the same email path — with RESEND_API_KEY set, invited members receive their invite code by email; the code stays visible in Settings → Members either way

Audit log

Every state-changing action is appended to an immutable trail with the actor, target, timestamp, and a small details object. Reads are never recorded. The actor is resolved from the request credential to a member name or email; actions taken by an unlinked API key (or, in open mode, by no credential at all) resolve to the workspace owner or to no actor.

{
  "logs": [
    {
      "id": "77b21c09aa04",
      "action": "approve",
      "actor_id": "3c1a9f22bd10",
      "actor_name": "Dana Ortiz",
      "target_type": "run",
      "target_id": "af772b3602ef",
      "details": { "node_id": "review" },
      "created_at": "2026-07-07T14:12:40Z"
    }
  ],
  "total": 128
}

Metrics

{
  "total_runs": 412,
  "success_rate": 91.4,
  "total_cost_usd": 1.83271,
  "active_workflows": 3,
  "runs_by_day": [
    { "date": "2026-06-24", "count": 28, "cost_usd": 0.1142 }
  ],
  "eval_pass_rate": 87.5,
  "evaluated_runs": 64
}

Members & RBAC

Access is governed by ten granular capabilities. A member's role supplies a default set; per-member overrides create exceptions in either direction; the effective permission is the override if one is set, else the role default. API keys linked to a member act with that member's effective permissions.

• admin holds all ten capabilities; editor holds the six above through publish_workflows; viewer holds only view
• Members carry a status: active, invited (holds an invite code), or pending(self-serve signup awaiting an admin's approval)
• The last active admin is protected: you cannot demote or remove them, nor deny them manage_members or manage_workspace — promote another admin first

How requests map to capabilities

The auth middleware maps each request to a required capability and returns 403 — "This action requires the 'X' permission" — when the credential lacks it.

{ "overrides": { "delete_workflows": true, "publish_workflows": false } }

API keys

API keys are role-scoped bearer credentials sent in the X-API-Keyheader. A key linked to a member acts with that member's effective permissions; an unlinked key uses its own role's defaults. The full secret (prefixed aos_) is returned once at creation — only a display prefix is stored. Keys are revoked (flagged), never hard deleted, and last_used_at updates on each authenticated request.

{
  "id": "5f2ab9013c77",
  "name": "CI pipeline",
  "prefix": "aos_1a2b3c4d…",
  "role": "editor",
  "member_id": null,
  "revoked": false,
  "secret": "aos_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
}

Usage

{
  "plan": "free",
  "runs_used": 274,
  "runs_limit": 1000,
  "cost_usd": 0.83104,
  "period_start": "2026-07-01T00:00:00Z",
  "period_end": "2026-07-31T23:59:59Z"
}

runs_limit is null on the enterprise plan. The period spans the first and last day of the current UTC month.

Authentication modes

Auth is a single environment switch. Local development runs open; set it to required in production and hand out session tokens or API keys.

• Exempt from auth even in required mode: /api/health, /api/auth/login, /api/auth/accept-invite, /api/auth/signup, and /api/hooks/*(a webhook's secret is its own credential)
• On restart, runs left running or pending become resumable failures — their last checkpoint is intact, so POST /api/runs/{id}/resume picks up where they left off