.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, thelocal, 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.
Changing a model
- Point a surface at another entry.
UTILS_VISION_MODEL,UTILS_TEXT_MODELandUTILS_OCR_MODELeach take an entry name, a list of names (the first whose key or server is present wins), aprovider/modelstring, or an inline entry. An environment variable of the same name overrides the file, for exampleUTILS_VISION_MODEL=qwen-utils. - Change the chat default.
DEFAULT_MODELnames aMODELSentry; unset, the first entry whose key or server is present is the default. - Route a key through another gateway.
<PREFIX>_BASE_URLin.env, wherePREFIXis the key’s name without_API_KEY, redirects every entry that reads that key to another OpenAI-compatible endpoint, for exampleOPENROUTER_BASE_URL.ANTHROPIC_BASE_URLis also read by Anthropic’s own SDK, so a machine that already sets it for another tool redirects Mirobody too;mirobody doctorprints the endpoint each surface resolved. - Add a vendor. Add an entry to
MODELSinconfig.llm.yamlwithllm_type: openai, itsbase_url,model, andapi_keyset to the name of the.envvariable that holds the secret. An entry used for vision must declaresupports_image: true. Add it toconfig.llm.yamlitself: aMODELSblock 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 .