Skip to content
Docs menu

Provider keys and setup

Add API keys for cloud providers, local engine URLs and voice providers to a self-hosted orchestrator without editing .env.

View .md

The orchestrator can take a provider's API key from the console instead of from .env. The console's Providers page shows one card per provider your build supports, and every card is backed by the admin API below.

What gets stored, and where

Each value is an environment variable the config already reads, such as MISTRAL_API_KEY or QWEN_BASE_URL. Values set from the console are saved in $VENOM_DATA_DIR/provider-keys.json with mode 0600, outside the repo, and applied when the orchestrator starts. If .env sets the same variable, the .env value wins and the console shows it as read-only.

The config file never holds a key. When a provider has no upstream in orchestrator.yaml yet, its block is appended with an api_key_env reference and the config reloads, which records a new entry in the config history. If the config file is read-only, as with the Docker compose mount, the key is still saved and the console shows the block to paste in yourself.

A key is never sent back. Responses say whether it is set, where it came from (env or stored) and its last four characters.

The admin API

All four endpoints take the admin token (Authorization: Bearer $VENOM_ADMIN_TOKEN).

Endpoint What it does
GET /admin/v1/providers Lists the provider cards: where to get a key, what it looks like, the region options, and the state of each field and upstream.
PUT /admin/v1/providers/{id} Saves values (field id to value) and, when the upstream is new, models. Appends the upstream block if the config has none, then reloads.
POST /admin/v1/providers/{id}/test Runs that upstream's own health check once, using the values you send on top of the saved ones. Nothing is saved. This is the only call made to the provider, and only when you ask for it.
DELETE /admin/v1/providers/{id}/key Removes the key saved from the console. The upstream stays in the config and is disabled until it has a key again.

Save a Mistral key and test it:

curl -X PUT -H "Authorization: Bearer $VENOM_ADMIN_TOKEN" -H 'content-type: application/json' \
  -d '{"values": {"api_key": "<your key>"}}' http://127.0.0.1:8787/admin/v1/providers/mistral
curl -X POST -H "Authorization: Bearer $VENOM_ADMIN_TOKEN" http://127.0.0.1:8787/admin/v1/providers/mistral/test

If you change a typed-in base URL while a key is set, you have to send the key again in the same request. Otherwise a saved key could be pointed at another host.

Providers

The cloud providers are OpenAI, Anthropic, Z.ai, Alibaba Cloud Model Studio (Qwen), Mistral, MiniMax, TypeSafe, Amazon Bedrock, Amazon SageMaker and any OpenAI-compatible API. The local engines are Ollama, vLLM, llama.cpp and SGLang, set by base URL. Voice providers such as ElevenLabs, Fish Audio and BytePlus Seed Speech, plus a local OpenAI-compatible speech server, appear when the orchestrator has their adapters. Bedrock and SageMaker have no cheap key check, so their test only confirms that the values are complete.

The full contract is in docs/architecture.md under Providers.