Owlbot

Owlbot is a modular, event-driven toolkit for extending Owncast servers with chat commands, interactive stream features, and custom integrations. It offers a drop-in module system where new functionality is added by dropping a Python module into a folder — no core changes or forking required.

Features

Custom commands: Moderators can create, edit, and delete chat commands at runtime without code changes or restarts. Responses support dynamic placeholders like $(user), $(count), $(rand), $(countdown), and positional arguments.
Quotes: Codify the streamer's hot takes, wild claims, and memorable one-liners said live on air. Moderators add quotes, and anyone can recall them at random or look up a specific quote by ID.
Timers: Set up recurring chat messages that fire on a simple duration or cron schedule. An optional minimum chat line threshold keeps timers from firing into an empty chat.

Owlbot's core is a framework for building and running modules. If the included modules don't cover your use case, you can write your own:

Modular architecture: Each module is a single Python file or package. Add, remove, or disable modules independently.
Event system: React to chat messages, user joins/parts, stream start/stop, name changes, and moderation events.
Command system: Register chat commands with permissions, cooldowns, and aliases.
Per-module storage: Each module gets its own SQLite database with automatic transaction management.
YAML configuration: One config file for the bot and all modules.
HTTP routes: Modules can serve web pages, APIs, and webhooks.

Getting Started

Prerequisites

Python 3.10+
A running Owncast 0.2.4 instance

1. Installation

Install Owlbot and its dependencies using pip. This procedure assumes Owlbot is being installed on the same system as Owncast, but this is not a requirement.

pip install git+https://git.logal.dev/LogalDeveloper/Owlbot.git@v1.0.0

This also installs a set of default modules.

2. Access Token

On your Owncast instance, open the Admin panel and navigate to Integrations > Access Tokens.
Click Create Access Token.
Give the token a name (e.g. Owlbot, Yapatron 4000, Stream Butler). This is the name that will appear in chat when the bot sends messages.
Select all permission scopes.
Save the token and copy it for the next step.

3. Configuration

Copy the example config:

cp config.example.yaml config.yaml

Set the Owncast server URL and the access token from the previous step:

owncast:
  url: "https://stream.logal.dev"
  access_token: "WeeEknOZhtCydC7dcgKoABlba8oaT82udpqyx5EgLLg="

4. Webhooks

These instructions assume Owlbot is running on the same system as Owncast.

Run the below command to generate the webhook URL. This is used by Owncast to send events to Owlbot.

$ owlbot --webhook-path
http://127.0.0.1:8081/webhook/TyeKM7ciVtaM0Zsb49akoRdJYKpdbxCD98neteUtU-c

Copy the printed URL.
Back in the Owncast Admin panel, navigate to Integrations > Webhooks.
Click Create Webhook.
Paste the URL from step 1.
Select all event types and save.

5. Reverse Proxy

Update the reverse proxy for the domain serving your Owncast instance to pass /owlbot/ traffic to Owlbot.

Caddy

If your Caddyfile looks like this:

stream.logal.dev {
        reverse_proxy http://127.0.0.1:8080
}

Add a section for the /owlbot/ path:

stream.logal.dev {
        reverse_proxy /owlbot/* http://127.0.0.1:8081
        reverse_proxy http://127.0.0.1:8080
}

6. Running

Start Owlbot from the directory containing your config.yaml:

owlbot

7. Verify

Start a stream on your Owncast instance and send !about in chat. If Owlbot replies, everything is set up and running.

That's it! Your Owlbot instance is now set up. Check out the pages below to learn more about what you can do with it.

Next Steps

Command Reference - Quick listing of all commands included with the default modules.
Configuration - All settings, environment variables, and config file options.
Modules - Writing custom modules for Owlbot.

Included Modules

Creating New Modules