---
title: "Managing providers"
manual: "LLM Foundation"
version: "0.42"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:administration-providers@0.42"
source: "Administration/Providers.rst"
rendered: "2026-11-01T11:38:21+00:00"
---

# Managing providers {#administration-providers}

Providers represent connections to AI services.
Each provider stores an API endpoint, encrypted
credentials, and adapter-specific settings.

![Provider list showing adapter type, endpoint URL, API key status, and actions](../Images/backend-providers.png)

## Adding a provider {#administration-providers-add}

1.  Navigate to **AI > Setup >
    Providers**.
1.  Click **Add Provider**.
1.  Fill in the required fields:

    -   ****Identifier****

        A unique slug for programmatic access
        (e.g., `openai-prod`, `ollama-local`).

    -   ****Name****

        A display name for the backend
        (e.g., `OpenAI Production`).

    -   ****Adapter Type****

        Select the provider protocol. Available
        adapters: `openai`, `anthropic`,
        `gemini`, `ollama`, `openrouter`,
        `mistral`, `groq`, `azure_openai`,
        `custom`, and the decision adapters
        `typesafe` and `decision_sidecar`
        ([Decision service](https://docs.typo3.org/permalink/netresearch/nr-llm:api-decision-service@0.42)).

    -   ****API Key****

        Your API key. Stored securely via
        [nr-vault](https://github.com/netresearch/t3x-nr-vault)
        envelope encryption. Leave empty for local
        providers like Ollama.
1.  Optionally set the endpoint URL, organization
    ID, timeout, and retry count.
1.  Click **Save**.

> [!TIP]
> Use the [Setup wizard](https://docs.typo3.org/permalink/netresearch/nr-llm:administration-wizards-setup@0.42) for guided
> first-time setup — it auto-detects the provider
> type from your endpoint URL.

## Setting the key from the command line {#administration-providers-set-key}

An unattended install cannot operate the
wizard. `nrllm:provider:set-key` does the
same job for a provider record that already
exists, reading the key from STDIN:

**Store a key for the "openai" provider**

```bash
printf '%s' "$OPENAI_API_KEY" | \
    vendor/bin/typo3 nrllm:provider:set-key openai
```

The key is never accepted as an argument — that
would put it in the process list and the shell
history. A terminal is refused rather than read,
so a provisioning script fails visibly instead of
hanging on a prompt.

Running it again for the same provider replaces
the stored key and keeps the identifier, so
anything already referring to that identifier —
including
`providers.openai.apiKeyIdentifier` in the
extension configuration, which the speech and
image services read — keeps working. See
[ADR-124](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-124@0.42).

## Testing a connection {#administration-providers-test}

After saving a provider, click
**Test Connection** to verify the setup.
The test makes an HTTP request to the provider API
and reports:

-   Connection status (success or failure).
-   Available models (if the provider supports
    listing).
-   Error details on failure.

![Provider test modal showing successful connection to Local Ollama](../Images/backend-provider-test.png)

> [!NOTE]
> Self-hosted endpoints (such as Ollama) reached through a hostname
> that resolves to a private or loopback address are subject to the
> SSRF protection built into nr-vault's HTTP client. If a connection
> test fails with a *"disallowed IP range"* error, add the endpoint
> host to the TYPO3 HTTP allowlist:
>
> **config/system/additional.php**
>
> ```php
> $GLOBALS['TYPO3_CONF_VARS']['HTTP']['allowed_hosts'][] = 'ollama';
> ```
>
> The request-time allowlist is honored by nr-vault 0.6.1 and later.
> Private and loopback IP literals are checked too. For an endpoint such
> as `http://127.0.0.1:11434`, allowlist the literal host `127.0.0.1`.
> Only an exact hostname or IP entry overrides the private-address block;
> a wildcard does not.

## Ollama model-list fallback {#ollama-model-list-fallback}

If fetching Ollama's model list fails, its adapter returns a small
predefined list for the model picker. These entries do not confirm that
those models are installed or that the endpoint is reachable. The
connection test still reports an unreachable endpoint as a failure.

The adapter attempts a diagnostic warning when it uses that list. A
failure while writing the warning does not prevent the fallback list
from being returned.

## Editing and deleting providers {#administration-providers-edit}

-   Click a provider row to edit its settings.
-   Use the **Delete** action to remove a
    provider. Models linked to a deleted provider
    become inactive.