---
title: Configure models and keys
description: Connect a model service and verify a real model call.
lastVerified: 2026-10-18
---

# 1.3 Configure models and keys

Before you begin, [start Teloa locally](https://docs.teloa.ai/v/0.2.0/markdown/en/start/quickstart.md). For a remote model, have an API key you are authorized to use. For a local model, prepare its runtime service and device resources. You pay remote model fees; the Community software license does not include inference credits.

## Open model settings

Open **Settings > Models** and find your model provider. Teloa manages business areas and employees; the underlying DSH settings manage models, keys, and the environment they run in.

Enter and save the key under the corresponding model provider. Then check that the provider, model name, and run configuration match. Do not put keys in an employee's responsibilities, group messages, skill content, or ordinary reference material.

[![DeepSeek provider settings with an empty API key field](https://docs.teloa.ai/v/0.2.0/assets/screenshots/en/model-settings.63c4d26e996a.png)](https://docs.teloa.ai/v/0.2.0/assets/screenshots/en/model-settings.63c4d26e996a.png)

*0.2.0-beta.3 interface before a key is entered. Enter your own key and save it. The empty field shown here does not indicate a working model connection.*

## Verify a response

Start a general conversation and enter:

```text
Reply only with “Model connection is working.” Do not use tools or access reference material.
```

Once you receive a response, test an employee task. Opening the page, saving a key, and successfully running a model task are three separate checks.

## Check the employee's configuration

If a regular conversation works but an employee task fails, check that employee's run configuration and the error message. Pause the employee before changing its employee definition or tool permissions. After saving, return the employee to active status and verify with a small task.

## Local chat models: Ollama

1. Install and start [Ollama](https://ollama.com/download) on the device that will run the model. Open **Settings > Models > Local models** and check its service status and version requirements.
2. Review the target Ollama address, model size, disk and memory guidance, and license. Choose **Download** and confirm. You can follow progress or cancel; Teloa does not install or start Ollama for you.
3. After downloading and connecting the model, select it in the conversation or employee's model configuration. Verify a response as described above, then test a real tool task. An existing unlisted model can be connected with **Connect as an unlisted model**; verify its capabilities separately.

Advanced address settings select the Ollama service that receives downloads and inference requests. If you enter another device's address, that device receives the model and context. With Docker, “local” refers to the deployment server or a service reachable from the container. A loopback address inside the container does not point to the computer viewing the browser; configure an address reachable from your deployment.

**Remove** disconnects the model and deletes its files from the Ollama service shown in the confirmation. An employee can have an explicitly selected remote fallback: only eligible primary-service failures trigger at most one attempt with the selected remote fallback. Without a selected fallback, the task reports failure rather than choosing another model automatically. A ready service, downloaded files, and a successfully completed task are separate results. Memory guidance is an estimate.

## Local search models

A search model turns materials into a searchable index; it does not generate chat answers. Open **Search settings** in the retrieval area under **Library > Local files**, select a model, and follow its preparation prompts:

| Model | Preparation |
| --- | --- |
| Qwen3 Embedding 0.6B | Review the model, tokenizer, and runtime downloads, choose an available source, and explicitly confirm. Teloa runs it on the deployment device; Ollama is not required. |
| EmbeddingGemma 2 | Install and start Ollama on the device running Teloa, meeting the version shown in the page, then confirm pulling and preparing the model. Choose another search model if the device is unsupported. |

Enabling retrieval or opening settings does not automatically download a model. Complete the confirmation and preparation, choose **Use this model**, then add the required materials to local retrieval. First preparation needs a network connection and disk space; you can cancel or retry a failed preparation. With Docker or a server deployment, these files and computations stay in that deployment environment, not the browser.

Embedding and indexing run on the deployment device, but retrieved excerpts may still be sent to the current conversation's remote chat model. See [Prepare and use reference materials](https://docs.teloa.ai/v/0.2.0/markdown/en/guides/knowledge.md#enable-local-indexing-and-search) for searchable scope and source checks.

## Common problems

| Symptom | What to do |
| --- | --- |
| Authentication fails | Check that the saved key is valid and belongs to the selected provider. Save it again and retry. |
| The model does not exist or is unsupported | Use a model identifier actually available from that provider. Check whether the run configuration still references an old model. |
| Insufficient quota or rate limiting | Check your quota and request limits with the model provider. A Teloa license does not automatically add tokens. |
| Network failure | Check access to the model service from the device running Teloa. A browser connection does not prove that Teloa can connect. |
| Conversation works, but a task using tools fails | Check the model's tool-calling support, the employee's permissions, and the execution record. |

The default setup targets DeepSeek. Configure other models, including models on a private network, according to what the current agent engine actually supports, and verify them separately. This guide does not promise that every compatible endpoint will work without changes.

External models receive the authorized context needed for the task. See [Privacy and permissions](https://docs.teloa.ai/v/0.2.0/markdown/en/deploy/privacy.md) for where data goes.