Providers

A provider is the host you send chats to: OpenAI, Anthropic, a local Ollama daemon, or any OpenAI-compatible URL. Providers are personal. They live in Settings > Providers and write providers.* in the user .vixl settings.json. A project folder cannot override them, and API keys never go in that JSON.

The model picker stays disabled until at least one provider exists. Adding a provider does not pick a default model. After you add one, set role models.

Add a catalog provider

1. Open Settings, then Providers.
2. Choose Add provider.
3. Pick an entry from AI SDK providers or OpenAI-compatible, or skip the catalog and add a custom endpoint.

The dialog searches by display name or id. Empty search shows the full catalog: first-party AI SDK packages plus a short OpenAI-compatible list Vixl ships (48 entries; table at the bottom).

Choosing a catalog id writes providers.<id>.apiKeyRef (the ref is that id). Unless the provider skips a key, Add API key opens next. Ollama and LM Studio skip that step.

API keys

Paste the key and save. An empty value is refused. Clear key removes the secret. The row shows whether a key is configured, missing, or optional.

The secret is stored as vixl:provider:<apiKeyRef>. Every keychain key must start with vixl:. The vault account vixl:vault is reserved and cannot be used as a secret name.

On macOS and Windows, Vixl uses the OS keychain service vixl and keeps one JSON vault under that account. On Linux it uses Secret Service when that is available. If Secret Service is missing or access is denied, it falls back to secrets-vault.json in the app config directory (not inside .vixl), created with mode 0600. Older per-key entries are merged into the vault the first time they are read.

MCP secrets use the same vault. Their key names are documented on MCP servers.

Test a connection

Use Test connection on a provider row (or in the custom-endpoint dialog) to probe the host. HTTP 401 or 403 means the key is wrong. Other failures include the server message when the body has one. Most hosts are probed with GET {baseURL}/models (Bearer only when a key is present). Catalog OpenAI-compatible hosts use their default base URL when you have not set another.

Local hosts

Ollama and LM Studio are in the OpenAI-compatible catalog and do not require an API key.

Test, live /models listing, and runtime all use those defaults. If Ollama's live list fails, the catalog fallback id is llama3.2.

Custom OpenAI-compatible endpoints

Custom OpenAI-compatible is for any host that speaks an OpenAI-style /v1 HTTP API, including a URL you run yourself. Defaults: name local, base URL http://localhost:1234/v1. The saved type is openai-compatible under providers.custom.<id>. The id is a slug of the name on create and stays the same if you rename later. Name must be at least one character. The base URL must be a valid URL. Invalid config is refused.

What the fields do:

• Name and base URL identify the endpoint.
• API key is optional. Leave it blank for local servers that do not authenticate.
• Include usage (on by default) asks the endpoint to return token usage with responses.
• Structured outputs (off by default) opts into structured-output support when the host implements it.
• Extra headers and query params are attached to requests.
• Models can be imported from {baseURL}/models, added by id, or left empty so Vixl lists live /models at pick time.

Import adds new ids and skips ones already in the list. If the endpoint returns none, the list is unchanged. Each model row needs an id. You can also set a display name, context and max tokens, tools / vision / thinking / stream flags, and USD-per-1M pricing. Missing pricing shows a warning. Advanced sampling, reasoning, per-model headers, and extra JSON options are optional.

Create and edit stay in the same dialog so you can import models, then save again. A custom row subtitle is the configured model count.

Routers

Point a custom OpenAI-compatible endpoint at a router, then import from /models. That GETs {baseURL}/models and adds new ids so you pick models instead of typing them. OpenRouter is also in the OpenAI-compatible catalog (openrouter, https://openrouter.ai/api/v1).

Remove a provider

Delete the row. Vixl removes the keychain secret and the providers.* settings keys for that id.

Provider refs and custom endpoint objects are stored in settings.json. Next, assign models to roles.