Repository navigation
Configuration
All configuration lives in a single YAML file (default config.yaml). It has three top-level sections: owlbot for core bot settings, owncast for the Owncast server connection, and modules for per-module settings.
A complete example is provided in config.example.yaml. Copy it and adjust for the target environment:
cp config.example.yaml config.yamlThese control the bot's web server, command system, storage, and handler behavior. Owlbot settings can be configured in the config file, environment variables, or CLI flags. When the same setting is specified in multiple places, the highest-priority source wins:
- CLI flag (highest)
- Environment variable
- Config file
- Default value (lowest)
owlbot:
host: "127.0.0.1"
port: 8081
command_prefix: "!"
handler_timeout: 30.0
storage_dir: "data"
modules_dir: "modules"
pool_size: 4
log_dir: ""
webhook_secret: ""
public_base_url: ""| Key | Default | Env Var | CLI Flag | Description |
|---|---|---|---|---|
host |
"127.0.0.1" |
OWLBOT_HOST |
--host |
Address to bind the web server. Set to "0.0.0.0" to listen on all interfaces. |
port |
8081 |
OWLBOT_PORT |
--port |
Port for the web server. |
command_prefix |
"!" |
OWLBOT_COMMAND_PREFIX |
Prefix character for chat commands (e.g., !help). |
|
handler_timeout |
30.0 |
OWLBOT_HANDLER_TIMEOUT |
Maximum seconds a handler can run before it is cancelled and its storage changes rolled back. | |
storage_dir |
"data" |
OWLBOT_STORAGE_DIR |
-s, --storage-dir
|
Directory for per-module SQLite database files. Each module gets a <module_name>.db file here. Relative paths are resolved from the working directory. |
modules_dir |
"modules" |
OWLBOT_MODULES_DIR |
-m, --modules
|
Directory containing Owlbot modules. Relative paths are resolved from the working directory. |
pool_size |
4 |
OWLBOT_POOL_SIZE |
Maximum SQLite connections per module in the connection pool. Connections are created lazily as needed. | |
log_dir |
(unset) | OWLBOT_LOG_DIR |
-l, --log-dir
|
Directory for the owlbot.log file. When set, logs are written to this directory in addition to stdout. When unset, logs go to stdout only. |
webhook_secret |
(auto-generated) | OWLBOT_WEBHOOK_SECRET |
Secret token for the webhook URL path (/webhook/<secret>). A cryptographically secure value is generated on first run and saved back to the config file automatically. |
|
public_base_url |
owncast.url |
OWLBOT_PUBLIC_BASE_URL |
Public base URL for generated links (e.g., "https://owlbot.example.com"). Set this if Owlbot is hosted on a different domain than your Owncast instance. |
These configure how Owlbot connects to the Owncast server.
owncast:
url: ""
access_token: ""
admin:
enabled: false
username: "admin"
password: "abc123"| Key | Default | Env Var | Description |
|---|---|---|---|
url |
required | OWLBOT_OWNCAST_URL |
Base URL of your Owncast server. Used to connect to the Owncast API. |
access_token |
"" |
OWLBOT_OWNCAST_ACCESS_TOKEN |
Integration API token. Generate one in Owncast Admin under Integrations > Access Tokens. Required for sending messages, hiding messages, listing clients, etc. |
admin.enabled |
false |
OWLBOT_OWNCAST_ADMIN_ENABLED |
Enable the optional Admin API client, which grants modules access to more parts of Owncast than what the main integrations API allows. |
admin.username |
"admin" |
OWLBOT_OWNCAST_ADMIN_USERNAME |
Username for Owncast Admin API authentication. |
admin.password |
"abc123" |
OWLBOT_OWNCAST_ADMIN_PASSWORD |
Password for Owncast Admin API authentication. |
Per-module configuration lives under the modules key. Each subkey is a module name. Unlike Owlbot settings, module settings can only be configured in the config file. Environment variables and CLI flags are not supported for module configuration.
Modules are enabled by default. To disable one, set enabled: false under its name:
modules:
ping:
enabled: falseModules may add their own config keys under their name. These appear in the config file after the module's first run:
modules:
custom_commands:
enabled: true
max_nesting_depth: 4| Key | Default | Description |
|---|---|---|
default_cooldown |
5 |
Default cooldown in seconds for newly created custom commands. |
max_nesting_depth |
4 |
Maximum nesting depth for placeholders. $( tokens encountered at or beyond this depth are treated as literal text. |
Built-in Modules
Creating New Modules