providers.*

providers.* is the LLM provider CRUD surface. Twelve methods are registered via register_config_handlers (src/bin/aleph-server/commands/start/builder/handlers/settings.rs:260-404) once the live Config is loaded. The create / update / delete / setDefault paths have two registrations each — a base handler plus a _hot variant — but the registry only ever exposes the hot variant; the multi_registry decides which is wired at boot, and a None registry falls back to the config-only path. The OAuth methods are registered separately through register_oauth_handlers next to the OAuth state cell.

The companion sub-namespaces (embedding_providers.*, generation_providers.*, rerank_config.*, runtimes.*, moa.*, routing_rules.*, voice.*, browser_config.*, fetch_config.*, search_config.*, memory_config.*, general_config.*, behavior_config.*, execution_config.*, route_config.*, generation_config.*, security_config.*, acp.*) are also wired by the same register_config_handlers call. They follow the same vault-backed config pattern; only acp.* is conditional on a built AcpAdapterManager.

Methods

providers.list

List every configured LLM provider. API keys are never returned; only their presence is reported.

Request: no params.

Response: { "providers": [ ...ProviderInfo... ] }. Each row carries name, enabled, model, models, provider_type, base_url, color, timeout_seconds, max_tokens, context_window, temperature, has_api_key, is_default, verified.

providers.get

Fetch a single provider by name.

Response: { "provider": { ...ProviderInfo... } } or INVALID_PARAMS with Provider not found: <name>. API key is never returned.

providers.create

Create a new provider. The API key, when supplied, is written to the vault (ai:<name>) and stripped from the in-memory config so it never lands on disk.

Response: { "ok": true } on success. INVALID_PARAMS if the provider already exists. With a live MultiProviderRegistry (provider_hot), the new provider is hot-registered so it is immediately usable as the default and as an auto-derived failover fallback.

providers.update

Patch an existing provider. Same ProviderConfigJson shape as create; fields present in the patch overwrite their existing value, others stay.

Response: { "ok": true } on success. Re-running providers.test against the updated name is the only way to flip verified back to true. With a live registry, the new ProviderConfig is hot-built and re-registered so protocol / base_url / model changes take effect on the next prompt.

providers.delete

Delete a provider. The API key is removed from the vault and the entry is scrubbed from the failover chain so deletion does not leave a dangling reference. With a live registry, the entry is also removed from the dialable set.

Response: { "ok": true } on success. INVALID_PARAMS when the name is unknown or the provider is the current default.

providers.test

Probe a single provider's connection. On success, verified is set to true and the failover circuit breaker is reset (so a rotated credential is tried immediately instead of staying shut out for the rest of the 10-minute cooldown).

Response: { "success", "error" | null, "latency_ms" | null } — see TestResult.

providers.setDefault

Promote a provider to default. The new default must already be verified. With a live registry, the swap is hot: the new provider is built, registered, and used as the default on the next prompt; the failover breaker is reset for the same reason as providers.test.

Response: { "ok": true } on success. INVALID_PARAMS when the name is unknown or the provider has not passed providers.test.

providers.needsSetup

Quick first-run check used by the Panel to decide whether to show the wizard.

Response: { "needs_setup", "provider_count", "has_verified" }. needs_setup is true iff no provider is both enabled and verified.

providers.catalog

Chat-window model picker. Joins the built-in chat presets with per-user credential state and per-model metadata. When view is omitted, returns only the verified+enabled rows; available returns every credentialed row, all returns every chat-capable row.

Response: { "items": [ ...CatalogEntryView... ] }. Each row carries id, display_name, default_model, base_url, protocol, color, homepage, notes, signup_url, fallback_models, default_aux_model, aliases, modalities, models, has_api_key, verified, enabled, is_default, capabilities (optional), cost (optional), endpoint (local/cloud), lifecycle (active/preview/deprecated), requires_explicit_model.

When MoA presets are configured, a synthetic id: "moa" row is appended with the preset names as its models. Selecting a MoA preset via model_override activates advisory fan-out for the session.

providers.healthcheck

Concurrent read-only liveness sweep over every configured provider. Disabled providers are reported as skipped rather than probed; per-provider failures are reported as rows, not as an RPC error.

Request: no params.

Response: { "providers": [ ...ProviderHealthRow... ] } sorted by name. Each row carries name, enabled, ok, skipped, latency_ms (optional), error (optional).

providers.modelsRefresh

On-demand discovery: ask each configured provider for its live /models list. Per-provider failures are returned as rows, not as an RPC error. The operator-facing counterpart of the list_models tool's refresh argument.

Response: { "providers": [ ...DiscoveryRow... ] } sorted by provider name. Each row carries provider, ok, fetched_at (optional), models (optional), error (optional).

providers.oauthLogin

Start a browser-based OAuth login (Codex / ChatGPT). Stores the full token blob (access_token + refresh_token + expiry) in the vault as ai:<provider>:oauth; the access token is also mirrored under ai:<provider> so existing provider code keeps working.

Response: { "connected": true, "provider", "expires_in_seconds" | null } on success. INVALID_PARAMS for any other provider name.

providers.oauthLogout

Clear the OAuth state. Deletes both ai:<provider> and ai:<provider>:oauth from the vault and clears the in-memory cache.

Response: { "ok": true }.

providers.oauthStatus

Read the current OAuth state. If the cached token is expired, attempts a refresh in-band (best-effort) and reports connected: false with a re-login hint if the refresh fails.

Response: { "connected", "provider", "expires_in_seconds" | null, "error" | null }.

Config Fields

ProviderConfigJson (providers.create / providers.update / providers.test):

models is normalised server-side — model (singular) is accepted as a legacy alias and merged into the multi-model list.

TestResult shape

providers.test and providers.healthcheck return rows with the same fields:

{
  "success": true,
  "error": null,
  "latency_ms": 245
}

providers.healthcheck always reports skipped: true and ok: false for disabled providers instead of probing them.

Companion namespaces

register_config_handlers also wires (in the same boot pass):

Each sub-namespace follows the same vault-backed pattern (API keys and secrets live in ai:<name> / embed:<id> / gen:<id> / web_fetch:<backend> / search:<backend>, never in the persisted config).

See Also

• Methods Reference -- All currently registered namespaces
• Configuration -- ~/.aleph/config.toml layout
• Models & providers -- Routing across the catalog