Grim Games Live Grim Games Live

GRiMbot documentation

Install on Windows

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

Install on Windows

Purpose and scope

This procedure installs a self-contained GRiMbot Core package on Windows 10 or Windows 11. It covers the installer and portable package. It does not cover developer source installations.

Prerequisites

  • A Windows x86_64 PC.
  • A GRiMbot Core package from the release location supplied by the distributor.
  • Permission to run an installer or extract an archive.
  • An unused local TCP port 8000.
Package Installation method Start command
GRiMbot-Core-*-win64-Setup.exe Run the installer and choose a folder. Start GRiMbot.bat
GRiMbot-Core-*-win64.zip Extract the complete archive to a permanent folder. Start GRiMbot.bat

[!IMPORTANT] Both packages include Python 3.12, dependencies, ffmpeg, and GRiMbOS. Do not install Python separately.

Procedure

  1. Download one Windows Core package.

  2. For the Setup package, run the executable and select an installation folder.

  3. On the final installer page, clear Launch GRiMbot now before finishing.

  4. If the installer has already launched GRiMbot, run Stop GRiMbot.bat before editing .env.

  5. For the portable package, extract every file into a permanent folder. Do not run GRiMbot from inside the zip archive.

  6. Open Command Prompt in the installation folder.

  7. Create .env only when it is absent, then open the file:

    if not exist .env copy .env.example .env
notepad .env

  8. Set ADMIN_USERNAME to a unique GRiMbOS username.

  9. Set ADMIN_PASSWORD to a unique GRiMbOS password.

  10. Save .env and close Notepad.

  11. Double-click Start GRiMbot.bat.

  12. Keep the GRiMbot console window open.

  13. Wait for the browser to open http://127.0.0.1:8000/admin.

  14. If the browser does not open, enter that address manually on the same PC.

  15. Continue with First login, then SETUP BOT.

Settings and choices

Choose a folder that your Windows account can read and write. A short path such as C:\GRiMbot makes database backup and plugin installation easier to manage.

Use the Setup package for a normal installed copy. Use the portable package when you need an extracted folder with no installer registration. Both packages use their bundled runtime and have the same admin address by default.

Use Stop GRiMbot.bat to stop GRiMbot. Closing the console window also terminates the process, but the stop script is the normal shutdown path.

When updating an existing installation, edit the existing .env. Do not replace it with .env.example.

The packaged launcher binds to 127.0.0.1 on port 8000. It does not accept connections from another computer. The current packaged release does not supply a supported two-PC network deployment.

Expected result

The GRiMbot console remains open without a fatal error, and GRiMbOS loads at:

http://127.0.0.1:8000/admin

Verification checklist

  • [ ] Start GRiMbot.bat exists in the installation root.
  • [ ] .env contains a unique ADMIN_USERNAME and ADMIN_PASSWORD.
  • [ ] The GRiMbot console remains open after startup.
  • [ ] http://127.0.0.1:8000/admin loads from the same PC.
  • [ ] The GRiMbOS sign-in screen appears.
  • [ ] data\grimbot.db exists after GRiMbot initializes the database.
  • [ ] Stop GRiMbot.bat stops the running process.

Failure handling

If the browser opens before the API accepts requests, wait several seconds and refresh once.

If the address still fails, inspect the GRiMbot console. A message that port 8000 is already in use usually means another GRiMbot instance or another program owns the port. Run Stop GRiMbot.bat, close other GRiMbot console windows, and start one copy.

If Windows blocks an extracted script, open the archive properties before extraction and use Unblock when that option is present. Extract the archive again after unblocking it.

If the console closes immediately, run Start GRiMbot.bat from a Command Prompt opened in the installation folder so the error remains visible.

[!NOTE] A single-PC installation uses Twitch EventSub over WebSockets when no public base URL is configured. Follows, subscriptions, and other EventSub events do not require a tunnel.

Security and data notes

[!SECURITY] Do not publish .env or data\grimbot.db. Keep backups in a protected location.

The .env file can contain the Twitch Client Secret, OAuth tokens, the GRiMbOS password, and integration credentials. Restrict access to the installation folder.

Related pages