Provider Reference¶
Supported providers¶
| Provider | Kind | Credential | Default model / execution | Capabilities |
|---|---|---|---|---|
| OpenAI | Model API | OPENAI_API_KEY | profile default | invocation, streaming, tools, structured output, health |
| Claude (Anthropic) | Model API | ANTHROPIC_API_KEY | profile default | invocation, streaming, tools, structured output, health |
| Gemini | Model API | GEMINI_API_KEY | profile default | invocation, streaming, tools, structured output, health |
| OpenRouter | Model API | OPENROUTER_API_KEY | openrouter/auto | invocation, streaming, tools, structured output, health |
| Ollama | Local model | none | llama3.2 | invocation, streaming, tools, structured output, health, model discovery |
| Codex | Agent host | host auth or OPENAI_API_KEY | codex exec | agent execution, auth, MCP host |
| Cursor | Agent host | host auth or CURSOR_API_KEY | cursor-agent | agent execution, auth, MCP host |
| Windsurf | Agent host | host-managed | authenticated GUI host | auth status, MCP host |
Configure and verify¶
ai-workspace providers init openai --apply
ai-workspace credentials configure openai --apply
ai-workspace providers limits openai --mode budgeted --monthly-request-limit 100 --apply
ai-workspace providers verify openai
ai-workspace providers invoke openai --prompt "Return OK" --apply
ai-workspace providers stream openai --prompt "Return OK" --apply
Profiles store references, never secret values. Runtime requests enforce prompt, token, timeout, retry, and monthly request policies. Retryable failures use bounded exponential backoff; credentials and payloads are excluded from logs.
Use providers update to preview migration into .ai-workspace/providers/registry.json; add --apply to commit after the plan is reviewed. Compatibility evidence expires after 90 days for hosted providers and 180 days for pinned Ollama versions.
The local dashboard saves selected provider models as profile metadata and never as credentials. It may display status-discovered Ollama models, while hosted model IDs are validated before storage. A consented test returns and retains only bounded operational metadata—never prompt or response content. See the provider configuration guide for the key-slot and dashboard workflow.
Offline fixture integrity is verified with SHA-256 after canonical UTF-8 line-ending normalization. This prevents checkout-specific CRLF conversion from invalidating otherwise identical evidence across supported operating systems.
Best practices¶
- Use environment variables or encrypted local storage for development; use an approved secret manager in production.
- Start with guarded or budgeted policy mode.
- Run
verifybefore invocation and rotate credentials after suspected exposure. - Prefer Ollama for workflows that must avoid remote data egress.
For failures, inspect provider status and credential status; never paste keys into issue reports. See Security.