Skip to main content
For most deployments, add secrets to .env and choose a model in the setup page. Use config.{ENV}.yaml for settings that differ from the shipped defaults.

Configuration files

Configuration precedence, from highest to lowest: environment variables, the overlay, config.devices.yaml and config.llm.yaml, then config.yaml. A dictionary does not merge across files: a key set in the overlay replaces the whole value, so an overlay that sets EMAIL_PREDEFINE_CODES replaces the demo accounts rather than adding to them. ENV selects the overlay file and labels logs. Enable production mode with PRODUCTION; naming an environment prod does not enable it. In the overlay, a value whose name contains _KEY, _PASSWORD, _PASS, _PWD, _SECRET, _SK or _TOKEN is encrypted with CONFIG_ENCRYPTION_KEY from .env.

Models

Every surface runs on one vendor key or on the local models. The first-run page (./deploy.sh prints its link while no model is set up; Settings › Model later) saves either choice encrypted in the database, applies it without a restart, and never overrides a value set in .env. Saving takes the SETUP_TOKEN from .env and, once a model is set up, a signed-in session as well.

A vendor key

Put one of these in the .env next to compose.yaml, then apply it:
docker compose restart does not re-read .env; up -d does. ./deploy.sh writes a key given in its environment into .env (OPENROUTER_API_KEY=sk-or-... ./deploy.sh), so a first run needs no second step. Each key selects a model for three surfaces: chat (the model picker), vision (report photos and scanned pages) and text (indicator extraction, file titles, summaries and journal sentences). The table at the top of lists what each key selects and where each key is issued. The model’s name is yours to change: the first-run page shows it beside the key, and in .env the variable each entry names as its model_env (OPENROUTER_CHAT_MODEL, for one) replaces it; a vendor model is checked with one real request before it is kept.

Local models

With no key, the local, local-utils and local-ocr entries serve every surface from an OpenAI-compatible server on your machine. The runtime Mirobody ships a preset for is llama.cpp’s llama-server: the first-run page finds the server, lists what it serves and loads the size you choose. The same choice, written in .env:
UTILS_OCR_MODEL is a fourth surface: a document-OCR model that reads report photos and scanned pages before any other model, and whose tables are read by their headers, with no model. Its shipped value is the local-ocr entry. HF_ENDPOINT in .env points the one-time model download at a Hugging Face mirror. A vendor key in .env outranks the local entries, and the first-run page refuses 100% on this machine while one is there. To run the local models beside a key anyway:

The doctor report

mirobody doctor prints the keys and local servers it found and the entry each surface selected, and names the fix for a surface that has none. --probe sends each surface one real request (a tool call, a schema-bound answer, an image, the OCR passes) and checks that a local server runs the model its entry names; it costs a few tokens on a vendor and minutes on a local model.
The server and the worker log the same report at startup.

Changing a model

  • Point a surface at another entry. UTILS_VISION_MODEL, UTILS_TEXT_MODEL and UTILS_OCR_MODEL each take an entry name, a list of names (the first whose key or server is present wins), a provider/model string, or an inline entry. An environment variable of the same name overrides the file, for example UTILS_VISION_MODEL=qwen-utils.
  • Change the chat default. DEFAULT_MODEL names a MODELS entry; unset, the first entry whose key or server is present is the default.
  • Route a key through another gateway. <PREFIX>_BASE_URL in .env, where PREFIX is the key’s name without _API_KEY, redirects every entry that reads that key to another OpenAI-compatible endpoint, for example OPENROUTER_BASE_URL. ANTHROPIC_BASE_URL is also read by Anthropic’s own SDK, so a machine that already sets it for another tool redirects Mirobody too; mirobody doctor prints the endpoint each surface resolved.
  • Add a vendor. Add an entry to MODELS in config.llm.yaml with llm_type: openai, its base_url, model, and api_key set to the name of the .env variable that holds the secret. An entry used for vision must declare supports_image: true. Add it to config.llm.yaml itself: a MODELS block in the overlay would replace the whole table.

Deployment settings

The keys that decide how the agent behaves are described in The Agent.

Secrets

PG_ENCRYPTION_KEY is a separate value from CONFIG_ENCRYPTION_KEY: it encrypts stored content such as chat messages and uploaded files. DATABASE_DECRYPTION_KEY (hex) encrypts the device credentials the providers store. Do not copy either key between environments. Generating these secrets yourself and moving them to another host is described in Deploy on a Server.

Extension directories

The engine scans three lists of directories at startup. Adding one extends the engine without editing the package. An overlay that sets one of these replaces the list, so repeat the default entry beside your own. An installed package can extend the same three through the mirobody.tools, mirobody.agents and mirobody.providers entry points instead. The complete reference for every configuration key is .