---
title: AI provider
description: Connect an OpenAI-compatible AI endpoint for AI Chat and the AI Agent — switch the AI module on, enter the endpoint and key, test it, and set limits.
url: https://nexcmp.com/docs/ai/ai-providers/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# AI provider

> **Where in the admin:** System › Settings › AI provider (`/settings/ai`). The AI module switch is there and on System › Admin › License & updates (`/license`), card **Module**.

## What it does

AI Chat (automatic support chat) and the AI Agent (VM administration in plain language) do not ship with a built-in model. You choose **your own provider**: any service that offers an **OpenAI-compatible** `chat/completions` API — for example OpenAI, OpenRouter, a LiteLLM gateway or your own vLLM server. NexCMP stores the endpoint and the API key (encrypted) and uses them for every AI feature. You pay the provider directly.

## Requirements

| Item | Requirement |
|---|---|
| Endpoint | An OpenAI-compatible base URL (`https://api.openai.com/v1`, `https://ai.example.com/v1`). NexCMP appends `/chat/completions` to a URL that ends in `/v1`; for any other URL it appends `/v1/chat/completions`; a URL that already ends in `/chat/completions` is used as is. |
| Model | A model that supports **tool (function) calling**. Both AI Chat and the Agent rely on it. |
| API key | A key for that endpoint. Prefer a key with a **spending cap** on the provider side (for example a LiteLLM virtual key with a monthly budget). |
| Network | The panel server must reach the endpoint over HTTP(S). A URL typed in the form is only allowed to point to the Internet on ports 80, 443, 8080 or 8443; to use an internal address save the provider first and then test. |
| Dependencies | The **AI** module on. For the Agent see [AI Agent](https://nexcmp.com/docs/ai/ai-agent/#requirements). |

## Prepare the infrastructure

1. Sign up with the provider and create an API key. If the provider supports budgets or rate limits, set a monthly limit.
2. Note the **base URL** and the exact **model name** (and, optionally, up to four fallback models).
3. Test it from the NexCMP server before entering it:

   ```bash
   curl -s https://ai.example.com/v1/chat/completions \
     -H "Authorization: Bearer XXXX" -H "Content-Type: application/json" \
     -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Reply with one word: OK"}]}'
   ```

   A JSON answer with `choices[0].message.content` means the endpoint works.

## Connect in NexCMP

1. Open **System › Settings › AI provider**.
2. In the card **Module AI** switch the module **on**. Until it is on, customers do not see AI Chat or the AI Agent in the portal. (You can also switch it in **License & updates**.)
3. In the card **Connection** fill in:

   | Field | Example | Notes |
   |---|---|---|
   | Use this provider | on | Needs a base URL, a model and a key to be switched on. |
   | Display name | `LiteLLM` | Up to 60 characters. |
   | Base URL (OpenAI-compatible) | `https://ai.example.com/v1` | `http://` or `https://`, up to 300 characters, no spaces. |
   | Provider API key | `sk-XXXX` | Stored encrypted; afterwards only the last 4 characters are shown. Leave empty to keep the stored key. |
   | Default model | `gpt-4o-mini` | Letters, digits and `- _ . / : @`. |
   | Fallback models | `gemini-2.5-flash` | Comma separated, up to 4. Used when the default model fails. |
   | Reasoning effort | Default (not sent) | `Minimal`, `Low`, `Medium` or `High`. For reasoning models (Gemini, o-series) a low level answers much faster. Leave on Default for normal models. |

4. Click **Save**, then **Test connection**. The test sends one short question and shows `Connected — <model>, <ms> ms` or the error returned by the provider.

![AI provider page with the AI module switched on and the connection form filled in with example values](https://nexcmp.com/docs/images/ai/ai-providers-01-connection.webp)


### What saving does

- The provider settings are saved as one configuration entry and the key is encrypted with AES-256-GCM, bound to this purpose, using the installation's master key.
- The support settings **Primary model** and **Fallback model** (used by AI Chat) are set to your default and first fallback model automatically.
- The change is written to the audit log (endpoint, model, whether the key changed — never the key).

## Verify

1. **Test connection** shows green.
2. Sign in to the portal as a test customer: the menu now offers **AI Chat** (or the chat bubble) and **AI Agent**.
3. Ask AI Chat "What is my balance?". An answer that quotes your real balance shows that the provider handles tool calls correctly.

## Limits & notes

- **One provider.** NexCMP uses a single configured provider for Chat, Agent and ticket investigation. Fallback models give resilience within that provider.
- **Key safety.** The saved key is sent only to the saved endpoint. If you change the Base URL you must type the key again before testing.
- **Limits per customer.** AI Chat is for signed-in customers only, with per-minute and per-chat message limits. The Agent has a daily call limit per account. See [AI Chat](https://nexcmp.com/docs/ai/ai-chat/) and [AI Agent](https://nexcmp.com/docs/ai/ai-agent/).
- **Privacy.** Customer questions and the data the AI reads for that customer (read-only) are sent to your provider. Say so in your [privacy policy](https://nexcmp.com/docs/customers/legal/).
- **Cost control.** NexCMP does not meter AI cost; use the provider's budget features.
- The module can be switched off at any time: the AI menu items disappear and the AI routes answer 404 `module_disabled`. Some background jobs of AI Chat (ticket investigation, delayed replies) pick up the change at the next restart of the panel.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `base_url must be an http(s) URL` | Missing scheme or spaces | Use `https://host/v1`. |
| `api_key is required to enable the provider` | No key stored | Enter the key and save. |
| `base_url and model are required to enable the provider` | Empty field | Fill both. |
| "Base URL blocked: public http(s) only, ports 80/443/8080/8443" | Testing an unsaved internal address or other port | Save the provider first, then test. |
| `api_key is required (enter the key again when you change the endpoint)` | The Base URL differs from the saved one | Retype the key. |
| `model: letters, digits and - _ . / : @` | Invalid character | Use the provider's exact model id. |
| `fallback_models: up to 4 model names` | Too many | Keep four or fewer. |
| Test fails with 401 | Wrong key | Check the key and the endpoint. |
| Test fails with 404 or "model not found" | Wrong path or model | Check the base URL (`/v1`) and the model id. |
| `Too many tests — wait a minute` (429) | More than 10 tests per minute | Wait. |
| Portal still shows no AI menu | Module off, or provider not "in use" | Turn the module on and enable the provider. |