What GRiMbot does

GRiMbot is a self-hosted Twitch chat bot. It connects Twitch events and Chat Messages to configured responses, overlays, media, Action Chains, stream controls, and optional plugins. GRiMbOS is the browser-based administration interface used to configure and monitor the installation.

This page defines the system boundary. It explains which work GRiMbot performs, which services remain external, and which functions require additional setup.

flowchart TB
    T[Twitch Chat and EventSub] --> C[GRiMbot Core]
    C --> U[GRiMbOS /admin]
    C --> O[Overlay HTTP pages]
    O --> OBS[OBS Browser Source]
    C --> P[Installed plugins]
    P --> X[Spotify / OBS / Discord / games]
    C --> D[(data/ and .env)]

System components

IMPORTANT

GRiMbOS may open while one or more external connections are unavailable. A working administration page does not prove that Twitch, OBS, or a plugin service is connected. Check System Status and Connection Status.

Core responsibilities

Twitch chat

GRiMbot can join the configured Twitch channel, receive Chat Messages, match Core Commands and Custom Commands, and post authorized responses. Command behavior depends on configuration, Permissions, Cooldown, and the state of any required plugin.

Twitch events

GRiMbot can respond to supported Twitch events through Event Alerts and related stream functions. Twitch authorization must include the Twitch Permissions required by each function.

Use Event Emulator for controlled testing when the target Event Alert supports it. An emulated event tests GRiMbot configuration. It does not prove that Twitch can deliver the live event.

Action Chains

An Action Chain contains one or more configured actions. Point Redemptions, Custom Commands, Button Box, Event Alerts, and other supported functions can run Action Chains.

Run Actions controls whether the actions run in order or at the same time. Delay affects an Action Chain that runs in order. Cooldown prevents immediate repeats where the feature provides that setting.

See Action Chains and Action Type Reference before building a chain that controls an external service.

Media and overlays

GRiMbot stores configured media references and provides browser-based overlays for OBS. Overlay Browser is used to locate and manage available overlay output. Media Library is used to manage media available to supported functions.

OBS renders the Browser Source. GRiMbot does not replace OBS scene composition, audio routing, encoder settings, or stream output configuration.

Stream administration

GRiMbOS provides windows for routine operation, configuration, status, community records, Twitch functions, media, overlays, and plugins. The available windows depend on the installed GRiMbot version and enabled plugins.

System Status reports GRiMbot service state. Connection Status reports configured external connections. Logs and Diagnostics provides evidence for fault isolation.

Plugins

Plugins add functions that are not part of the required core installation. A plugin may connect an external service, add GRiMbOS windows, add commands, or provide a Chat Game.

Installing a plugin does not authorize its external service. Complete the plugin page and verify its Connection Status before relying on it during a Stream Session.

Chat Games

Chat Games are optional plugins played through Twitch chat. Games Integration provides shared support for installed Chat Games.

If a website connects to the same GRiMbot installation, Casino is the only Chat Game that supports website play. Other Chat Games may provide website statistics or guides, but they do not accept website play.

External dependencies

GRiMbot depends on external software or services for some results.

NOTE

An external service may change availability, permissions, or account requirements independently of GRiMbot. Connection Status and Logs and Diagnostics distinguish many connection faults from configuration faults.

Data and persistence

GRiMbot stores operational data on the host you control. This includes configuration, the database, installed plugin data, and authorization material. The exact locations and recovery boundaries belong in Data Files.

A browser cache is not a Back Up. Copy the documented data set while following the Back Up procedure. Test the Restore procedure before depending on a Back Up for recovery.

SECURITY

Treat the GRiMbot data directory and Back Up copies as sensitive. They may contain Twitch authorization data, integration credentials, configuration, Chat Messages, and community records.

Network boundary

GRiMbot and GRiMbOS use local network services. A Two-PC setup requires network access between the systems involved. Plugin connections may require additional outbound or local network access.

Do not expose GRiMbOS, overlay administration, the database, data files, or diagnostic output to the public network unless a documented deployment procedure requires it and appropriate access controls are in place.

Read Network and Ports and Security before changing firewall, router, proxy, or remote-access settings.

What GRiMbot does not do

GRiMbot does not provide these external responsibilities:

• It does not create or manage your Twitch account.
• It does not replace the Twitch Developer application or Twitch authorization process.
• It does not replace OBS scene design, encoding, or stream output.
• It does not make an unavailable external service respond.
• It does not grant Twitch Permissions that the account has not authorized.
• It does not make plugin functions available before the plugin is installed and configured.
• It does not turn an untested file copy into a verified Back Up.
• It does not provide website play for Chat Games other than Casino.

Capability map

Readiness checklist

Before using GRiMbot during a live Stream Session:

• [ ] GRiMbot runs without a startup error.
• [ ] GRiMbOS opens from the intended operator system.
• [ ] System Status shows required services as running.
• [ ] Connection Status shows required external systems as connected.
• [ ] The configured Twitch account has the required Twitch Permissions.
• [ ] Core Commands respond according to their Permissions and Cooldown.
• [ ] Required OBS Browser Sources load and remain visible.
• [ ] Required plugins are installed, enabled, configured, and tested.
• [ ] Event Alerts and Action Chains pass controlled tests.
• [ ] A current Back Up exists and the operator knows where it is stored.
• [ ] Logs and Diagnostics is available if a fault occurs.