Bring your own model

The tools are deterministic TypeScript. The model only plans, calls tools and writes the answer, so you can plug in any engine.

Pick a providerCopy Anchor Link

Set these variables in next/.env.local (gitignored) and restart:

ExamplesCopy Anchor Link

# Anthropic (default model claude-opus-5-5, low effort)
AI_PROVIDER=anthropic
AI_API_KEY=...

# A local model through Ollama or LM Studio
AI_PROVIDER=openai-compatible
AI_BASE_URL=http://127.0.0.1:11434/v1
AI_MODEL=your-local-model

# Any OpenAI-compatible gateway (OpenRouter, vLLM, a company gateway)
AI_PROVIDER=openai-compatible
AI_BASE_URL=https://your-gateway.example/v1
AI_API_KEY=...
AI_MODEL=provider/model-id

Smaller local models may call tools less reliably. The golden questions in evals/fixtures are meant for comparing engines on the same questions once the live suite is built.

Or set it in the admin panelCopy Anchor Link

A superuser can set the provider, model id, API key, base URL, maximum steps and Anthropic fallbacks in Admin › Model. Each field set there overrides its environment variable; "Use environment default" goes back to the env value. Changes apply to new chats within a few seconds, without a restart.

• Storing a key needs SETTINGS_ENCRYPTION_KEY on the server (base64 of 32 random bytes, or 64 hex characters). Keys are encrypted with AES-256-GCM and never shown again: the form says only whether a key is stored.
• Keys stay with their address. AI_API_KEY from the environment is used only while the provider and the base URL also come from the environment (or the defaults). If you change either of them in the admin panel, enter the key for the new endpoint in the same save; otherwise the save is refused. This keeps a key from being sent to a host it was not meant for.
• Addresses. In production the base URL must use https, and it may not resolve to a private, loopback or link-local address unless the server sets ALLOW_PRIVATE_UPSTREAMS=1 (useful for a model server on your own network).
• Recent login. Model changes need a login from the last 15 minutes; the panel asks for your password again when needed.
• Reasoning effort is not a setting: it comes from AI_EFFORT only and is shown read-only.

How the agent talks to the modelCopy Anchor Link

• One model per conversation. Every response carries the model id, and a saved chat remembers the model it started with. If the model changes, the next turn in an older chat is refused and the user starts a new chat.
• A byte-stable system prompt and the full tool list from the first turn. Nothing about the user, the locale or the date is interpolated into the prompt, and tools are always listed in the same order. Consent-gated tools are present from turn 1 and only run after approval.
• Operator settings are versioned. The display name, the operator instructions and the switched-off tools from the admin panel form a block appended after the locked prompt. Each combination is stored once as a prompt version, and a chat keeps the version it started with on every turn, so the prompt never changes mid-conversation. A switched-off tool stays in the tool list and refuses to run. See Accounts and admin.
• Reasoning is kept. Reasoning parts and their provider metadata stay in the conversation and are sent back unchanged.
• toolChoice: auto only. The prompt asks the model to call plan first; nothing forces a tool.
• Anthropic options: low effort, thinking summaries between tool calls, server-side fallbacks (AI_FALLBACKS=off or Admin › Model disables them) and prompt caching. A refusal shows a notice instead of an answer.
• Errors. Provider error text is shown to superusers only; everyone else sees a generic message, so keys, internal addresses and gateway details never reach visitors.

No model at allCopy Anchor Link

• Replay mode plays scripted demos: the tools run live on the current data and the narration is templated from their results. It is the default when no model is configured.
• REST and MCP serve every public tool without any model. See REST API and MCP.

Use the tools from your own AI clientCopy Anchor Link

Any MCP client (Claude, ChatGPT, Cursor, VS Code and others) can connect to /mcp and use the tools with its own model. Nothing on the server calls a model for MCP or REST requests.

Accounts and termsCopy Anchor Link

Whoever runs a public instance must use API keys on an account they own, within the provider's terms and supported regions. The live chat has a geofence (AI_GEOFENCE_DENY or Admin › Access, ISO country codes; it reads the country header of the platform named in TRUSTED_IP_HEADER, Cloudflare or Vercel) and rate limits per signed-in user, per guest IP and for all guests together. Behind a proxy, set TRUSTED_IP_HEADER so guests are counted per IP rather than in one shared bucket.