For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/web/ai.md (or send Accept: text/markdown).
AI features
Chat, tasks, model policy, and bring-your-own-key.
Try fake AI, then choose a real provider
For your first result, follow the Web tutorial's /dashboard task: start the local flow, queue a prompt, run it and view the result. AI_PROVIDER=fake returns a repeatable demonstration response without sending data to an external model or using a paid API key.
For real generation, first configure persisted accounts, choose an AI provider and follow AI configuration below. Add a model and its price to the database catalog, choose the permitted models for each alias, and grant the workspace the required access. An alias such as fast is a friendly choice shown to the user; it is not itself an external provider's model ID.
A background AI task also needs the configured jobs service. If no model choices are shown, inspect the catalog and alias policy before retrying. If access is denied, inspect the active workspace's entitlement. Keep all provider API keys in the Web server's configuration, not the browser, mobile app or desktop window.
Follow the task lifecycle
The production task API validates the authenticated workspace and entitlement before persisting a task and dispatching the ai.generate Trigger.dev workflow. The router applies capability requirements and configured model policy.
POST /api/ai/tasks
→ authenticated workspace + entitlement
→ durable task record
→ Trigger.dev ai.generate
→ model routing + generation
→ usage record + result
→ transactional completion deliveryConfigure aliases and budgets
The user selects an enabled alias: cheap, fast, or smart. The server controls the underlying model IDs, provider credentials, workspace policy, and budget enforcement. Encrypted bring-your-own-key support must preserve the same server-only boundary.
Keep workflow semantics explicit
JobRunner promises enqueue, status, and cancel only. Trigger.dev workflow semantics are explicit, including durable execution behavior. Do not infer retries or scheduling guarantees from the generic contract.
The production submission path uses idempotency and saved task recovery to handle ambiguous dispatch. Completion of generation is separate from completion-email delivery.
Setup and configuration
AI_PROVIDER=fake keeps development deterministic. Production providers are configured server-side (OpenAI, Anthropic, or an OpenAI-compatible endpoint) with keys that never enter client bundles. AI_MODEL_POLICY maps the user-facing aliases — cheap, fast, smart — to catalog model ids; an empty alias removes the choice from the interface.
The model catalog (ai-model-catalog) carries capability metadata and immutable pricing so usage records stay explainable after prices change.
POST /api/ai/tasks → durable task + Trigger.dev dispatch
GET /api/ai/tasks/{taskId} → status + result
/chat → streaming assistant surfaceImplementation workflow
The chat surface keeps threads per workspace member and streams tokens through chat-stream-runtime. Longer generations run as tasks: authorized at the API boundary, executed by the ai.generate workflow, and recoverable through the idempotent submission store.
Bring-your-own-key mode stores provider keys as AES-GCM envelopes (CREDENTIAL_ENCRYPTION_KEY, byok-key-vault.ts); decryption happens only inside the server execution path. Usage and estimated cost are recorded per request for workspace budgets.
Verification and troubleshooting
Verify a disabled alias is absent from the interface, entitlement and budget denials happen before dispatch, a retried submission reuses its task, and a stored BYOK key is never returned to the client. Keep real-model acceptance on the documented provider smoke path.