Grim Games Live Grim Games Live

GRiMbot documentation

What you need

This is the hosted copy of the GRiMbot technical manual. Use the table of contents to open any page in the manual.

GRiMbot product page Manual home

What you need

Purpose and scope

Use this page to choose a supported GRiMbot layout and collect the accounts, software, and network access required before installation. GRiMbot runs on hardware you control. It is not a hosted bot service.

Prerequisites

  • A Twitch broadcaster account.
  • Access to the Twitch Developer Console.
  • A Windows 10 or Windows 11 x86_64 system, or a Linux amd64 or arm64 system.
  • OBS Studio 28 or newer if you plan to use overlays or OBS Integration.
  • Permission to install software on the selected machines.

[!IMPORTANT] Official packages contain Python 3.12, required Python packages, ffmpeg, and prebuilt GRiMbOS files. Do not install system Python, Docker, or developer tools for a packaged installation.

Supported packaged layout

The current packaged release supports a local layout. GRiMbot Core, GRiMbOS, and any OBS Browser Sources run on the same machine.

Package Supported operator access
Windows installer or portable zip Use GRiMbOS and OBS on the Windows PC running GRiMbot.
Linux Debian package or tar archive Use GRiMbOS in a local browser on the Linux machine. 
flowchart LR
    Twitch[Twitch] <--> Core[GRiMbot Core]
    Core --> Admin[Local GRiMbOS browser]
    Core --> Overlay[OBS Browser Source]

Official Windows and Linux launchers bind GRiMbot to 127.0.0.1. The current packaged release does not supply a supported network deployment for a two-PC layout. The PC Agent does not change that boundary.

Procedure

  1. Confirm that the local packaged layout meets the stream requirements.
  2. Confirm the Twitch broadcaster account that owns the channel.
  3. Decide whether to use a separate Twitch bot account. This account is optional. Without it, GRiMbot sends Chat Messages as the broadcaster.
  4. Confirm that the broadcaster can create a Twitch application during SETUP BOT.
  5. Choose a GRiMbOS username and a unique GRiMbOS password. These credentials protect /admin and are unrelated to Twitch credentials.
  6. Identify the channel login in lowercase, as it appears in the channel URL.
  7. Identify the correct IANA Bot Timezone, such as America/Chicago.
  8. Select the optional software required by the stream.

[!SECURITY] Do not reuse a Twitch password for GRiMbOS. Treat the Twitch Client Secret, OAuth tokens, PC Agent token, GRiMbOS password, and data/grimbot.db as secrets.

Settings and choices

Core does not contain optional plugins or Chat Game packs. Install only the items used by your stream.

Requirement Additional software or account
Overlays OBS Studio 28 or newer. Enable Control audio via OBS on each Browser Source that plays sound.
Song requests Spotify Premium and an active Spotify playback device.
TTS Streamer.bot, Speaker.bot, and the Streamer.bot plugin. Same-PC installations can use direct localhost mode. The PC Agent is required when Use streaming PC agent is enabled.
Voice Recognition Follow the requirements on the Voice Recognition page.
OBS control OBS Integration and OBS WebSocket. The PC Agent is required when OBS Integration uses Agent mode.
Discord posts A Discord bot application with access to the target server.
AI replies An AI Account configured for a supported AI Provider.
ATS data The ATS Integration plugin and its SCS telemetry DLL.
MSFS data The MSFS Integration plugin and Little Navmap with its web server running.
StreamElements data The StreamElements plugin and its required account credentials.

Expected result

The local packaged layout meets the stream requirements. The required Twitch accounts, machine access, channel login, and Bot Timezone have been identified.

Verification checklist

  • [ ] The selected GRiMbot machine matches an available package architecture.
  • [ ] The Twitch broadcaster account can open the Twitch Developer Console.
  • [ ] The channel login is known in lowercase.
  • [ ] A separate bot account decision has been made.
  • [ ] A unique GRiMbOS username and password have been chosen.
  • [ ] The Bot Timezone is known.
  • [ ] OBS Studio 28 or newer is installed if overlays or OBS Integration will be used.

Failure handling

If the Linux architecture is unknown, run:

uname -m

Use an amd64 package for x86_64. Use an arm64 package for aarch64.

If the stream requires GRiMbot and OBS on separate machines, the current packaged release does not meet that requirement. See Two-PC setup for the boundary that applies to separately managed deployments.

Security and data notes

  • GRiMbot stores its SQLite database at data/grimbot.db in packaged installations.
  • Local installations use Twitch EventSub over WebSockets when no public base URL is configured. A public URL is not required.
  • Keep .env and data/grimbot.db out of public downloads, screenshots, and support posts.

Related pages