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

Clips: Capture and save moments from the live stream. Viewers clip directly from chat and trim their footage in a browser-based editor, no extra software needed.
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.
Emoji Wall: Display floating emojis and custom emotes from chat as animated particles in an OBS browser source overlay.
Polls: Run interactive polls in chat with live results. Moderators create polls through a web form, viewers vote by number in chat or on a voting page, and results update in real time.
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 connection 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

uv — handles Python and dependency management automatically
A running Owncast 0.2.5 instance
ffmpeg (optional) — required by the clips module for video processing. If not installed, the clips module will not load but all other modules will work normally.

1. Installation

Create a directory for Owlbot, set up a virtual environment, and install the package. This procedure assumes Owlbot is being installed on the same system as Owncast, but this is not a requirement.

mkdir owlbot && cd owlbot
uv venv --python 3.14
uv pip install owlbot \
  --default-index https://git.logal.dev/api/packages/LogalDeveloper/pypi/simple/ \
  --index https://pypi.org/simple
uv run owlbot init

uv venv creates a virtual environment with the required Python version, downloading it automatically if needed. uv pip install installs Owlbot and all dependencies. owlbot init creates a default config.yaml. Built-in modules ship with the package and are loaded automatically.

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

Open config.yaml (created by owlbot init in step 1) and 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.

$ uv run 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.

uv run 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.

Built-in Modules

Creating New Modules