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/setup-ai.md (or send Accept: text/markdown).
Set up AI
Real models behind cheap / fast / smart aliases — keys stay on the server.
Setup and configuration
Before any step, read Before you start and Terminal basics. These instructions assume you opened the full supastack monorepo in VS Code; its root package.json marks the repository root. In pnpm commands, a workspace package is an app or shared-code folder; in the product, a workspace is a team's data container and security boundary. corepack pnpm --filter ... selects one package from the monorepo while commands run from its root. If you opened only a synced mobile or desktop folder, it does not contain the Web backend, Docker setup, or root scripts: run the backend from this monorepo or a reachable hosted server, and use the platform folder's own scripts. An environment variable is a named setting stored in a local .env file or your hosting dashboard; restart the relevant app after changing it, and keep server secrets out of NEXT_PUBLIC_ and EXPO_PUBLIC_ values.
1. Open apps/web/.env.local for the local Web server and apps/web/src/agent-runtime.ts for provider selection; .env.example is the list of supported setting names.
2. Keep AI_PROVIDER=fake for local interface work unless you have your own provider account and want to test real generation; never put provider keys in a NEXT_PUBLIC_ or EXPO_PUBLIC_ setting.
3. Start the Web app from the repository root with corepack pnpm --filter @supastack/web dev. Expected: local screens can be explored without configuring a paid provider; actual generation requires a valid server provider and enabled model choices in the database catalog.
The default AI_PROVIDER=fake supports local deterministic work. Real provider configuration belongs in the server environment. The provider keys listed in .env.example include OpenAI, Anthropic, and an OpenAI-compatible endpoint.
AI_MODEL_POLICY contains ordered model IDs for cheap, fast, and smart aliases. An empty alias list disables that choice. Model IDs must correspond to enabled database catalogue entries with effective immutable pricing.
AI_MODEL_POLICY='{"cheap":[],"fast":["catalog-model-id"],"smart":["catalog-model-id"]}'
AGENT_FRAMEWORK=ai-sdk # ai-sdk | mastra | langgraph | openai-agentsCommands to copy
Follow the comments to see which folder a command runs in. If two terminals are labeled, open two terminal windows and keep the first command running while you use the second.
corepack pnpm --filter @supastack/web devImplementation workflow
Configure the catalogue and workspace policy before accepting production tasks. The browser receives enabled aliases, while capability matching, model selection, entitlement checks, and budget enforcement stay on the server.
Keep credentials out of NEXT_PUBLIC_ and EXPO_PUBLIC_ variables. For bring-your-own-key mode, use the existing encrypted envelope and server decryption boundary; never return a stored provider key to the interface.
Verification and troubleshooting
If the app reports that no AI model is available, check the server's AI_PROVIDER, the enabled models and prices in the admin catalog, and the cheap/fast/smart alias policy. If a real provider returns an authentication error, check its key in apps/web/.env.local and restart the server. A key prefixed NEXT_PUBLIC_ would be visible to browsers and must be removed.
Verify disabled aliases, missing capabilities, inactive entitlement, and exhausted budgets. Use a separately authorized provider smoke run for actual generation. If no alias is available, inspect server policy and catalogue configuration rather than exposing a raw model selector.
If you want to continue setup, read Set up background jobs.