Skip to content

Configuration

Logan Fick edited this page Feb 13, 2026 · 8 revisions

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.yaml

Owlbot Settings

These 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:

  1. CLI flag (highest)
  2. Environment variable
  3. Config file
  4. 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.

Owncast Settings

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.

Module Settings

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.

Enabling and Disabling Modules

Modules are enabled by default. To disable one, set enabled: false under its name:

modules:
  ping:
    enabled: false

Module-Specific Keys

Modules 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

Custom Commands

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.

Clone this wiki locally