Skip to main content
mAItion can install one custom workspace model automatically the first time the stack boots. This page explains the mechanism, the JSON file format, and how to add a model of your own.

​
Adding a Custom Model

To install your own workspace model instead of the bundled example:
  1. Copy an existing file under models/, for example models/wikiteqcenturion.json, to a new file such as models/my-model.json. Keep the JSON array wrapper.
  2. Edit the fields you want to change — typically id, name, params.system, and meta.toolIds. Leave base_model_id as-is; it gets overwritten at install time regardless of what you put there.
  3. Set CREATE_CUSTOM_WORKSPACE_MODEL=my-model.json in your .env file.
  4. Start the stack.
This installs only during first-start initialization — the setup that runs only once, the first time the container boots, gated on a marker file. Setting CREATE_CUSTOM_WORKSPACE_MODEL on an already-running instance does not install it retroactively.

​
Overview

The ./models directory is mounted read-only into the container at /etc/owui-models (see compose.yaml). On first boot, the entrypoint can take one JSON file from that directory and install it as a workspace model tied to your default model. The repository ships one example: models/wikiteqcenturion.json.

​
How It Works

The bootstrap logic lives in helpers/entrypoint.sh and runs only when both of these are true:
  • ENABLE_OPENAI_API=True
  • OPENAI_DEFAULT_MODEL is set to a non-empty model ID

​
Selecting a model file

CREATE_CUSTOM_WORKSPACE_MODEL controls which file installs, if any:
  • True installs the bundled wikiteqcenturion.json.
  • Any other non-empty value is treated as a filename under models/ — for example CREATE_CUSTOM_WORKSPACE_MODEL=my-model.json installs models/my-model.json.
  • False or unset installs no custom model.
The entrypoint validates the selected file exists before doing anything else — including before it signs up the admin user or configures any provider. If the file is missing, the container exits immediately with an error and no side effects.

​
What happens to the default model

OPENAI_DEFAULT_MODEL configures a base model — a provider-derived model registered with your provider configuration. Setting it alone does not create a workspace model. Whether a workspace model gets created from it, and how visible that model is, depends on CREATE_CUSTOM_WORKSPACE_MODEL:
  • If no custom model file is selected, the entrypoint creates a workspace model for OPENAI_DEFAULT_MODEL and makes it public.
  • If a custom model file is selected, the entrypoint instead creates the OPENAI_DEFAULT_MODEL workspace model as private, and adds the custom model file as its own, public workspace model — with its base_model_id pointed at OPENAI_DEFAULT_MODEL (see below).
Both cases require first-start bootstrap to run, ENABLE_OPENAI_API=True, and OPENAI_DEFAULT_MODEL to be set — this is not unconditional behavior.

​
Runtime overrides

A few environment variables modify the installed model before it’s created:
  • The entrypoint always overwrites the file’s base_model_id with OPENAI_DEFAULT_MODEL at runtime. Whatever value the file itself has for base_model_id is ignored.
  • OWUI_MODEL_PROMPT, if set, fully replaces the file’s params.system prompt.
  • OWUI_MODEL_PROMPT_APPEND, if set, appends to the system prompt (bundled or already replaced by OWUI_MODEL_PROMPT), separated by a blank line.

​
JSON File Format

A custom model file must be a JSON array, with the model definition as the array’s first item — the entrypoint reads and installs only .[0] of the file. A file shaped as a bare JSON object instead of an array will not install correctly. The following table documents the fields present in the bundled models/wikiteqcenturion.json example:

​
Configuration Reference

These environment variables control workspace model bootstrapping. ENABLE_OPENAI_API and OPENAI_DEFAULT_MODEL are also documented in Environment Variables (Frontend).