Manual Setup

Note

Users who want to use Docker Compose should skip this wizard, see Docker Compose for the containerized install path.

This is the manual install procedure for technical users who’d rather not use the guided wizard. If you want the hand-held path, use the setup wizard instead as it creates .env, generates a safe CRYPTO_SECRET, configures PostgreSQL, and runs the install for you.

Prerequisites

• Bun
• PostgreSQL installed natively, or run in a Docker container (see step 2)

PostgreSQL schema, pgcrypto, seeds, and migrations initialize automatically on bot startup.

1. Install

git clone https://github.com/Bredrumb/TomoriBot.git
cd TomoriBot
bun install --frozen-lockfile

2. Configure

Create your environment file from the example and fill in the required values:

cp .env.example .env

Required:

• DISCORD_TOKEN: your Discord bot token (enable the GuildMembers, MessageContent, and GuildPresences privileged intents).
• CRYPTO_SECRET: a 32-character encryption key (used to encrypt stored API keys).
• PostgreSQL connection: POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB.
• ALLOW_PRIVATE_NETWORK: true, false, or a host:port list. See Private networks to choose.

Keep a protected copy of your encryption secret separately from database backups. New backups contain no .env. For rotation, use CRYPTO_SECRET_V1, CRYPTO_SECRET_V2, or any later positive integer version, with optional CRYPTO_SECRET_CURRENT selection.

No native PostgreSQL?

Run just the database in a container, then point the POSTGRES_* values at it:

docker run -d --name tomori-db \
  -e POSTGRES_USER=tomori -e POSTGRES_PASSWORD=yourpassword -e POSTGRES_DB=tomori \
  -p 5432:5432 pgvector/pgvector:pg16

Then set POSTGRES_HOST=localhost, POSTGRES_PORT=5432, and the user/password/db above. The pgvector/pgvector image ships the RAG extension pre-installed; swap it for postgres:16 if you don’t need document/RAG memory. This runs only the database in Docker and the bot still runs on host Bun. For a fully containerized bot and database, use Docker Compose instead.

Optional tuning lives in .env.optional.example. Copy over any values you want to customize (limits, timeouts, feature toggles, local server URLs, etc.).

Keep the data/ directory on persistent storage. Local files can include persona avatars and sprites in data/avatars/, voice samples in data/voice-samples/, and custom expressions in data/custom-expressions/. The database is stored separately, so back it up alongside these files.

3. Run

bun run dev

When you see TomoriBot up and running!, go to Discord and run /setup in your server to connect an AI provider and initialize the bot. The command opens a guided checklist panel, and nothing is written until you press Finish Setup;

Use bun run launch instead of bun run dev if you want optional local servers (SearXNG, Crawl4AI, local TTS/STT) launched alongside the bot:

bun run launch --searxng --crawl4ai
bun run launch --help        # see all flags

Optional extras (the manual “Full Install”)

The setup wizard’s Full Install path layers lightweight extras on top of the base install. None are required to run the bot, but each unlocks a feature. If you’re installing by hand, add whichever you want:

pgvector : document/RAG memory

RAG (document uploads and cross-channel recall) stores embeddings in a vector column, which needs the pgvector extension. Install it for your PostgreSQL major version:

# Debian/Ubuntu, e.g. for PostgreSQL 16
sudo apt-get install -y postgresql-16-pgvector

Then enable it once on your database. Connect with psql using the POSTGRES_* values from your .env: it prompts for POSTGRES_PASSWORD:

Windows

There is no prebuilt pgvector package for native Windows PostgreSQL. Installing it means building from source against your exact PostgreSQL version with Visual Studio C++ and nmake (see pgvector’s Windows instructions). The simpler path on Windows is to run the database in the pgvector/pgvector container shown under Configure above, which ships the extension pre-installed.

# Native / host psql (substitute your own POSTGRES_USER and POSTGRES_DB):
psql -h localhost -p 5432 -U tomori -d tomodb

# Or, if the database runs in the Docker container from step 2:
docker exec -it tomori-db psql -U tomori -d tomori

Once connected, run:

CREATE EXTENSION vector;

Without pgvector the bot still runs but RAG features become completely unavailable. This extension is also required on the target database before restoring a backup; see Maintenance & Backups for details.

pg_cron : scheduled cleanup jobs

pg_cron powers optional periodic database maintenance (cooldown/reminder-row cleanup). Docker Compose from this repo already configures it.

Not required for reminders or triggers

pg_cron performs purely housekeeping as it only cleans up stale rows. Reminder delivery and random triggers run in the app itself, so those features work with or without pg_cron.

For a self-managed PostgreSQL, find your active config file:

SHOW config_file;

Enable the extension in postgresql.conf: append to shared_preload_libraries if it already lists other libraries:

shared_preload_libraries = 'pg_cron'   # e.g. 'pg_stat_statements,pg_cron'
cron.database_name = 'your_dbname'

Restart PostgreSQL, then:

CREATE EXTENSION IF NOT EXISTS pg_cron;

Tokenizer assets

NovelAI text generation and model-aware logit bias need local tokenizer assets:

bun run setup:tokenizers

Some families (e.g. Gemma) are gated and require a HuggingFace token after you accept their license:

# Windows (PowerShell)
$env:HF_TOKEN="hf_xxx"; bun run setup:tokenizers

# macOS/Linux
HF_TOKEN=hf_xxx bun run setup:tokenizers

Missing assets disable optional logit bias. NovelAI text generation requires its three tokenizer families and returns a setup error if they are missing or invalid. These families use pinned public MIT definitions and need no Hugging Face token. To install only those families:

bun run setup:tokenizers --family novelai_nerdstash_v2
bun run setup:tokenizers --family novelai_llama3
bun run setup:tokenizers --family novelai_glm

The downloader writes to the repository’s tokenizers/ directory. If TOKENIZER_ASSET_DIR points elsewhere, copy the downloaded family directories there. Restart TomoriBot after installing or repairing assets, because the runtime caches load failures.

The secure fetch_url fallback and the DuckDuckGo web_search fallback both run in process, so neither needs an extra installation.

Maintenance, updating & backups

Once you’re installed, the host-side scripts (bun run update, bun run backup, bun run restore-backup, bun run nuke-db, bun run rotate-keys, …) and the update and backup procedures all live on the Maintenance & Backups page. If you’re about to pull a new version, start with Maintenance & Backups.