MitDesk docs
Getting started

Connecting a model

6 min read Odoo 20.0

MitDesk does not answer until it has a model and the provider is set up. This page shows you how to add a key or a server address, test it, and understand where your data goes.

Who this is for: a MitDesk administrator.

You need: Edition: Basic and above. See Editions. You need the group MitDesk Administrator for everything on this page.

Steps

  1. Open MitDesk ▸ Configuration ▸ Settings.
  2. In the block AI keys, type the key for your provider. For Ollama, type the address of your server.
  3. Click Save. Save before you test a new key.
  4. Click Test next to the key. You should see "valid".
  5. In the block Default model, choose the model that new agents use.

What you should see: after you click Test, the line next to the key says "valid".

The AI keys block in Settings: Anthropic, OpenAI, Gemini, Mistral and Ollama each with a Test button, and self-hosted servers below

The block has one entry for each of these providers:

Provider What you enter
Anthropic API key
OpenAI API key
Gemini API key
Mistral API key
Ollama Address of your Ollama server, for example http://localhost:11434
Self-hosted servers and gateways Click Manage AI endpoints. See Your own server

Each entry shows "set" when a value is stored, or "using environment configuration" when the value comes from a server environment variable. After a test, you see "valid" or "auth failed". Under Advanced configuration you see the parameter name and the environment variable, for example MINDDESK_ANTHROPIC_API_KEY.

Models

A model is a record under MitDesk ▸ Configuration ▸ Engine ▸ AI Models. It says which provider to call, which model name to send, how many tokens it can use, and what it costs.

The AI Models list with provider, provider class, context size and token costs

MitDesk ships with four models: Claude Opus 4.8 (the default), Claude Sonnet 5, Claude Haiku 4.5 and Mistral Large.

A model has one of seven providers: Anthropic, OpenAI, Gemini, Mistral, Ollama, OpenAI-compatible endpoint, or Named endpoint. Use Named endpoint for a server you added under AI endpoints.

Useful fields on a model:

  • Technical id is the name sent to the provider, for example claude-opus-4-8.
  • Context window and max tokens set the size of the conversation and of one answer.
  • Token rates are used to count cost. A model with no rates adds no cost to your budget.
  • Where it sends data shows the hosting class. See The hosting class.
  • Test connection sends one small real request to the provider. Only a MitDesk Administrator can use it, because it uses real credentials and costs tokens. The model records the time and the result, but not the provider's error text.

A daily job can ask each provider which models it offers and add the missing ones. It is off by default. To turn it on, enable the scheduled action MitDesk: sync provider model catalog (turn on developer mode, then Settings ▸ Technical ▸ Automation ▸ Scheduled Actions). New models arrive inactive. The job never changes the price, the default or the active state of a model you already have, and it never deletes a model.

Max tokens

Max tokens is the most one answer may contain. The default is 1024. MitDesk sends exactly this number to the provider. The only exception is an Anthropic model that uses the older "extended thinking" mode. There MitDesk raises the limit so that the answer still fits after the thinking.

If you give an agent a reasoning model and the response style Thorough, raise the max tokens. Otherwise answers can end early. The agent form tells you if the style changes how the chosen model works.

Your own server

An AI endpoint is the address of an OpenAI-compatible server that you run or rent, for example vLLM in your server room, or an EU-hosted service.

  1. Open MitDesk ▸ Configuration ▸ Engine ▸ AI endpoints, or click Manage AI endpoints in Settings.
  2. Click New.
  3. Enter a Name and the Base URL. The address must start with http:// or https:// and normally ends in /v1.
  4. If the server needs a key, type it in API key. MitDesk stores it and never shows it again. Leave the field empty to keep the current key.
  5. Click Save, then Test connection.
  6. Add a model with the provider Named endpoint and choose this endpoint.

The endpoint form: name, base URL, key, and "Where this sends data" set to On-premises

Each endpoint has its own key slot, so two endpoints never share a key. Test connection only checks that something answers at the address. It does not check the key. A wrong key gets an answer from the server, so the test still reports success. This avoids sending you to the firewall because of a typing mistake.

The AI endpoints list with one on-premises server

See Running it on your own hardware for what changes when the model runs inside your network.

The hosting class

Every model and every endpoint has a hosting class: On-premises, EU cloud or Non-EU cloud. You cannot set it by hand. MitDesk works it out, and it uses this value when it decides whether data may leave. See Sovereign routing.

  • Named providers. Ollama is on-premises. Mistral is EU cloud. Anthropic, OpenAI and Gemini are non-EU cloud.
  • Endpoints. An address on a private network (such as 192.168.x.x or 10.x.x.x), a loopback address, or a name ending in .local, .internal, .lan, .localdomain or .home.arpa counts as on-premises. A short list of known EU hosts counts as EU cloud. Everything else, including an address MitDesk cannot read, counts as non-EU cloud. MitDesk reads the name only. It does not look it up in DNS.

The region next to the class is a plain label. You may edit it. The class is checked again from the address every time data is sent, so an old or edited stored value cannot make a public host look local.

Where your keys are stored

MitDesk stores the keys you enter in Odoo's system parameters. Only administrators can read that table. The keys are encrypted. The encryption key depends on two things: the Odoo master password in odoo.conf (admin_passwd), and a secret inside the database. A copy of the database alone does not give away your keys.

Set a real master password

If admin_passwd is still the default admin, or is missing, the database copy holds everything needed to decrypt the keys. MitDesk writes a warning to the log until you change it.

Change the master password in the right order

If you change the master password without a preparation step, MitDesk can no longer read the stored keys. First run env["minddesk.secret"]._rotate_kek(new_admin_passwd) in odoo shell. Then change odoo.conf.

  • A key set as an environment variable (MINDDESK_<PROVIDER>_API_KEY) is used when no stored key exists. MitDesk does not store or encrypt it. Your server protects it.
  • A key saved by an older release may still be stored as plain text. It becomes encrypted the next time you save it. If you upgraded, enter each key once more.
  • If a stored key cannot be decrypted, MitDesk treats it as "not set".
  • The key fields in Settings show the stored key in a masked field. Anyone who can open that page can get the keys. You need both the Odoo Settings right and the MitDesk Administrator group to open it. Treat that combination as access to the keys.

Which servers may receive a key

MitDesk sends a key only to hosts on an allowlist. It checks this when it sends the request, not when you save the setting.

Built in: api.openai.com, api.anthropic.com, generativelanguage.googleapis.com, api.mistral.ai, api.groq.com, openrouter.ai and api.deepseek.com. Loopback addresses such as 127.0.0.1 are also allowed, because the key does not leave the machine.

A private network address such as 10.0.0.5 is not allowed automatically. To allow your own host, add it to the system parameter minddesk.endpoint_allowlist. Separate several hosts with commas or new lines. If a host is refused, the message names the host and the parameter.

If it does not work

If Test does not say "valid", check the key and save before you test again. For a refused key or a model that is not set up, see Troubleshooting.

Next steps