docs/configuration/README.md

## 🛠️ Configuration

The bot's behavior is controlled by a combination of [static](#static-configuration) and [dynamic](#dynamic-configuration) configuration.


### Static configuration

The bot can be configured using a [YAML](https://en.wikipedia.org/wiki/YAML) configuration file as well as [environment variables](https://en.wikipedia.org/wiki/Environment_variable).

When running the bot locally (during [🧑‍💻 development](../development.md)), the bot's configuration is read from the `var/app/config.yml` file.
This file is created from the template found in [etc/app/config.yml.dist](../../etc/app/config.yml.dist).

Certain keys can be left unset, in which case [📝 hardcoded defaults](../../src/entity/cfg/defaults.rs) would be used.

Some configuration keys found in the YAML configuration can be overridden by setting an environment variable (dots should be replaced with `_`). Example:

- to override `command_prefix`, set an environment variable `BAIBOT_COMMAND_PREFIX`
- to override `homeserver.server_name`, set an environment variable `BAIBOT_HOMESERVER_SERVER_NAME`

You can see the list of supported environment variables in the [🦀 src/entity/cfg/env.rs](../../src/entity/cfg/env.rs) file.

> [!WARNING]
> The static configuration contains an `initial_global_config` key, which is used to populate the bot's global configuration (stored as [dynamic configuration](#dynamic-configuration)) the first time the bot starts. Modifying this subsequently will not have any effect. After initial global configuration creation, it's expected to be managed dynamically via chat commands.

For Matrix-account authentication setup, see [🔐 Authentication](./authentication.md).


### Dynamic configuration

Besides the bot's [static configuration](#static-configuration), **the bot can also be configured dynamically at runtime (via chat messages)**.

This includes changes to [🔒 Access](../access.md), [🤖 Agents](../agents.md) and [🛠️ Room Settings](#room-settings).


#### Room Settings

Room Settings come from 3 different levels with priority in the following order (higher to lower):

- 📍 per-room (`!bai config room ..` commands)
- 🌐 globally (`!bai config global ..` commands)
- 📝 as [hardcoded defaults](../../src/entity/cfg/defaults.rs)

You can adjust the following settings per room and/or globally:

- [💬 Text Generation](text-generation.md)
- [🦻 Speech-to-Text](speech-to-text.md)
- [🗣️ Text-to-Speech](text-to-speech.md)
- [🖌️ Image Creation](image-generation.md)
- [🤝 Handlers](handlers.md)

Refer to the bot's help messages (as a response to a `!bai config` help command) for the most up-to-date information on what Room Settings can be configured.

You can **get an overview of the configuration affecting the current room** (a mix of hardcoded defaults, agent defaults, global and room-level settings) by sending a `!bai config status` command to the room.
Initial commit 2024-09-12 13:44:06 +03:00			`## 🛠️ Configuration`

			`The bot's behavior is controlled by a combination of [static](#static-configuration) and [dynamic](#dynamic-configuration) configuration.`


			`### Static configuration`

			`The bot can be configured using a [YAML](https://en.wikipedia.org/wiki/YAML) configuration file as well as [environment variables](https://en.wikipedia.org/wiki/Environment_variable).`

			When running the bot locally (during [🧑‍💻 development](../development.md)), the bot's configuration is read from the `var/app/config.yml` file.
			`This file is created from the template found in [etc/app/config.yml.dist](../../etc/app/config.yml.dist).`

			`Certain keys can be left unset, in which case [📝 hardcoded defaults](../../src/entity/cfg/defaults.rs) would be used.`

Minor documentation updates 2025-12-15 09:22:54 +02:00			Some configuration keys found in the YAML configuration can be overridden by setting an environment variable (dots should be replaced with `_`). Example:
Initial commit 2024-09-12 13:44:06 +03:00
			- to override `command_prefix`, set an environment variable `BAIBOT_COMMAND_PREFIX`
			- to override `homeserver.server_name`, set an environment variable `BAIBOT_HOMESERVER_SERVER_NAME`

Minor documentation updates 2025-12-15 09:22:54 +02:00			`You can see the list of supported environment variables in the [🦀 src/entity/cfg/env.rs](../../src/entity/cfg/env.rs) file.`

			`> [!WARNING]`
			> The static configuration contains an `initial_global_config` key, which is used to populate the bot's global configuration (stored as [dynamic configuration](#dynamic-configuration)) the first time the bot starts. Modifying this subsequently will not have any effect. After initial global configuration creation, it's expected to be managed dynamically via chat commands.
Initial commit 2024-09-12 13:44:06 +03:00
Document Matrix authentication modes Add a dedicated configuration/authentication doc covering password and access-token setup, including environment-variable mappings and token-generation example. Link to it from configuration docs and align the sample config wording with Matrix Authentication Service/OIDC terminology. 2026-03-07 11:08:41 +02:00			`For Matrix-account authentication setup, see [🔐 Authentication](./authentication.md).`

Initial commit 2024-09-12 13:44:06 +03:00
			`### Dynamic configuration`

			`Besides the bot's [static configuration](#static-configuration), the bot can also be configured dynamically at runtime (via chat messages).`

			`This includes changes to [🔒 Access](../access.md), [🤖 Agents](../agents.md) and [🛠️ Room Settings](#room-settings).`


			`#### Room Settings`

			`Room Settings come from 3 different levels with priority in the following order (higher to lower):`

			- 📍 per-room (`!bai config room ..` commands)
			- 🌐 globally (`!bai config global ..` commands)
			`- 📝 as [hardcoded defaults](../../src/entity/cfg/defaults.rs)`

			`You can adjust the following settings per room and/or globally:`

			`- [💬 Text Generation](text-generation.md)`
			`- [🦻 Speech-to-Text](speech-to-text.md)`
			`- [🗣️ Text-to-Speech](text-to-speech.md)`
Initial work on Vision support in text conversations and Image Editing This is a huge patch which does some major refactoring like: - renaming "Image Generation" to "Image Creation" in most places, to better match its new command (`!bai image create`) - relocating image creation command (`!bai image` -> `!bai image create`), so it wouldn't conflict with the new image editing command (`!bai image edit`) - introducing a new image editing command (`!bai image edit`), which is meant to work only with the OpenAI provider, but doesn't fully work yet due to https://github.com/64bit/async-openai/issues/364, though a next patch will fix it - adding support for reading images off of Matrix conversations and forwarding them to text conversations. Works for OpenAI, but not for Anthropic yet (requires custom patches) and not for OpenAI-Compat (no support for images there) - relocating some utils around (base64, mime) 2025-05-10 09:18:01 +03:00			`- [🖌️ Image Creation](image-generation.md)`
Initial commit 2024-09-12 13:44:06 +03:00			`- [🤝 Handlers](handlers.md)`

			Refer to the bot's help messages (as a response to a `!bai config` help command) for the most up-to-date information on what Room Settings can be configured.

			You can get an overview of the configuration affecting the current room (a mix of hardcoded defaults, agent defaults, global and room-level settings) by sending a `!bai config status` command to the room.