Install on Linux

Purpose and scope

This procedure installs a self-contained GRiMbot Core package on Linux amd64 or arm64. Use the Debian package when the system supports it. Use the tar archive when you need a folder-based installation.

Prerequisites

A supported 64-bit Linux system.
Root access when installing the Debian package or managing its service.
A GRiMbot Core package from the release location supplied by the distributor.
Local TCP port 8000 available. The Debian service uses port 8000 unless its systemd unit is overridden.

[!IMPORTANT] Official Linux packages contain Python 3.12, dependencies, ffmpeg, and prebuilt GRiMbOS files. Do not install system Python for a packaged installation.

Procedure

Identify the architecture

Run:
```
uname -m
```
Select the matching package.

`uname -m` result	Package architecture
`x86_64`	amd64
`aarch64`	arm64

Debian or Ubuntu package

Change to the directory containing the downloaded package.

Install the package that matches the machine:

sudo apt install ./grimbot-core_*_amd64.deb

For arm64, run:

sudo apt install ./grimbot-core_*_arm64.deb

Open the environment file:
```
sudoedit /opt/grimbot/.env
```
Set ADMIN_USERNAME to a unique GRiMbOS username.
Set ADMIN_PASSWORD to a unique GRiMbOS password.
Save the file.
Enable the grimbot service and start it:
```
sudo systemctl enable --now grimbot
```
Confirm the service state:
```
systemctl status grimbot
```
Open http://127.0.0.1:8000/admin in a browser on the bot machine.
Continue with First login, then SETUP BOT.

Tar archive

Change to the directory containing the archive.
Extract the package:
```
tar -xzf GRiMbot-Core-*-linux-amd64.tar.gz
```
Replace amd64 with arm64 when required.
Enter the extracted directory:
```
cd grimbot-core-*
```
Create the local environment file:
```
cp .env.example .env
```
Edit .env with the local text editor:
```
vi .env
```
Set ADMIN_USERNAME to a unique GRiMbOS username.
Set ADMIN_PASSWORD to a unique GRiMbOS password.
Save .env.
Start GRiMbot:
```
./start-grimbot.sh
```
Leave that terminal running.
Open http://127.0.0.1:8000/admin in a browser on the same machine.
Continue with First login, then SETUP BOT.

Settings and choices

The Debian package installs a grimbot systemd service. The supplied unit binds to 127.0.0.1 on port 8000. Changing APP_PORT in .env does not change that unit. An administrator must override the systemd unit to use another port.

Logs are available through journald:

journalctl -u grimbot

The tar archive runs in the current terminal and is suitable when you do not want a system package. Keep the extracted directory in a permanent location.

Packaged installations use SQLite. PostgreSQL and source setup scripts are developer options and are outside this operator procedure.

Both supplied Linux launch methods bind to 127.0.0.1. They do not accept connections from another computer. The current packaged release does not supply a supported two-PC network deployment.

Expected result

GRiMbot stays running, the health endpoint responds, and the GRiMbOS sign-in screen loads.

http://127.0.0.1:8000/health
http://127.0.0.1:8000/admin

Verification checklist

[ ] The package architecture matches uname -m.
[ ] .env contains a unique ADMIN_USERNAME and ADMIN_PASSWORD.
[ ] The grimbot service is active, or start-grimbot.sh remains running.
[ ] The health endpoint responds.
[ ] The GRiMbOS sign-in screen loads.

Failure handling

For a Debian installation, inspect recent logs:

journalctl -u grimbot -n 100 --no-pager

If port 8000 is already in use, stop the duplicate GRiMbot process or the conflicting service before restarting grimbot.

If ./start-grimbot.sh reports permission denied, run:

chmod u+x start-grimbot.sh
./start-grimbot.sh

If another computer cannot reach GRiMbot, that is expected with the supplied launchers. Do not change firewall rules or publish port 8000 as a workaround. Use the local browser.

Security and data notes

[!SECURITY] Set unique GRiMbOS credentials before the first login. Do not expose port 8000 directly to the public internet.

Do not publish the SQLite database or .env file. The .env file can contain the Twitch Client Secret, OAuth tokens, the PC Agent token, and integration credentials.