Agents
AI providers
How to connect hosted APIs, OpenAI-compatible servers and local model servers in Settings → AI Providers, test them, manage models and capabilities, and fix provider errors.
An AI provider is where model agents get their model: a hosted API, any server that speaks OpenAI Chat Completions, or a model server on your own computer. You connect providers in Settings → AI Providers; then you can create model agents on any of their models.
#Add a provider
- Open Settings → AI Providers and press Add provider.
- Choose a category:
- Built-in provider: well-known services with their settings filled in.
- OpenAI-compatible API: any endpoint that speaks Chat Completions.
- Local model: models served on this computer.
- Custom provider: full control over authentication, headers and paths.
- Choose a preset and fill in the form.
- Press Test connection. A working provider shows Connection works · N ms and the first few models it found.
- Press Add provider.
How you know it worked: the provider appears as a card with its model count and Key stored (encrypted), No key set or No authentication.
#Presets
| Preset | Base URL | Authentication | Notes |
|---|---|---|---|
| OpenAI | https://api.openai.com/v1 | Bearer token | GPT models through the Chat Completions API. |
| Anthropic | https://api.anthropic.com | x-api-key header | Claude models through the native Messages API. |
| Google Gemini | https://generativelanguage.googleapis.com | x-goog-api-key header | Token limits come from the native model list. |
| Azure OpenAI | https://YOUR-RESOURCE.openai.azure.com/openai/v1 | api-key header | Replace YOUR-RESOURCE. Use your deployment name as the model id. |
| AWS Bedrock | https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1 | Bearer (Bedrock API key) | OpenAI-compatible endpoint. Enter the model id manually; only models that support Chat Completions work. |
| OpenRouter | https://openrouter.ai/api/v1 | Bearer token | Many models behind one key. |
| Groq | https://api.groq.com/openai/v1 | Bearer token | |
| Together AI | https://api.together.ai/v1 | Bearer token | Namespaced model ids. |
| Fireworks AI | https://api.fireworks.ai/inference/v1 | Bearer token | |
| Hugging Face | https://router.huggingface.co/v1 | Bearer token | Suffix a model with :fastest or :cheapest to pick a backend. |
| OpenAI-compatible API | You enter it | Bearer, key optional | LiteLLM, a gateway, a hosted service. |
| Ollama | http://localhost:11434 | None | Capabilities and context size come from Ollama. |
| LM Studio | http://localhost:1234/v1 | None | Start its local server from the Developer tab. |
| vLLM | http://localhost:8000/v1 | None | Tool calling needs --enable-auto-tool-choice and a --tool-call-parser. |
| llama.cpp server | http://127.0.0.1:8080/v1 | None | Serves one model at a time. |
| Custom provider | You enter it | Configurable | Custom auth header, headers, chat and models paths, output-cap field. |
#The form
| Field | Notes |
|---|---|
| Provider name | Must be unique. |
| Request timeout (seconds) | 1 to 600. Default 60. |
| Base URL | Locked for presets with a fixed endpoint. Must be a full http:// or https:// URL. Remote endpoints must use https://; plain http:// is only allowed for localhost. Put credentials in the key field, not the URL. |
| Authentication | Bearer token, API key header (with Header name) or None. |
| API key | Encrypted with your OS keychain. When editing, leave it empty to keep the stored key. |
| Custom headers | Tick secret to store a value encrypted. Headers whose names look like credentials are always encrypted. |
| Chat path, Models path, Output cap field | Custom provider only. |
| Model ID (optional) | Models are discovered automatically where the provider lists them. Add one here if it does not. |
Test connection lists the models, which costs nothing. If the provider has no model list, LoCrew sends a one-token request to the model you entered instead.
#Models and capabilities
Expand Models and capabilities on a provider's card to see what it found. Refresh the list with the refresh button, or add a model by id. For each model you can override Tool calling, Vision, Streaming and Structured output (auto, yes or no), plus Context window and Max output tokens. Auto uses what the provider reported or what LoCrew learned from its answers.
#Removing a provider
Remove (click twice) deletes the provider. It is refused while agents use it: … is used by …. Move that agent to another provider first.
#Costs and limits
Model agents report tokens but no price, so the spend limits never stop them. Watch your provider's own billing. The hop, turn and queue limits still apply.
#Errors
| Message | What to do |
|---|---|
| … rejected the credentials (HTTP 401/403) | Check the API key and the authentication type. |
| … could not find that endpoint or model (HTTP 404) | Check the base URL and the model id. For Azure, use the deployment name. |
| … is rate limiting requests (HTTP 429) | Wait, or lower Max agents working at once. |
| … had a server error (HTTP 5xx) | A problem on the provider's side. Try again later. |
| Could not reach … : connection refused (is the server running?) | Start your local server (Ollama, LM Studio…). |
| … host not found / TLS certificate problem | Check the address and your network. |
| … the server tried to redirect; update the base URL to the final address | LoCrew refuses redirects. Use the final address. |
| … did not answer within Ns. | Raise Request timeout, or check the server. |
| … does not offer a model list. Enter the model id manually. | Type the model id. |
| Remote endpoints must use https://… | Use https:// for anything that is not localhost. |
| Replace YOUR-RESOURCE in the base URL with your Azure resource name. | Edit the Azure base URL. |
| Secure credential storage is not available on this system… | On Linux, install and unlock GNOME Keyring or KWallet. |
What is tested
Provider adapters are tested against a mock server for each wire format. The test suite contacts no commercial API. Native AWS SigV4, Vertex AI and Azure Entra ID sign-in are not supported.