[!NOTE] This README is a quick overview. For the full, up-to-date documentation (setup guides, feature walkthroughs, provider info, and more) visit docs.tomoribot.app.

A self-hosted and customizable personal AI assistant/role-playing system for Discord with memory, multiple personas, tool calling, multimodality, and API/local model support.

English | 日本語 Official Website · Invite TomoriBot · Discord Server Latest Releases · Report Bug · Request Feature

About the Project

TomoriBot is a free and open-source self-hosted personal AI assistant and role-playing system for Discord, inspired by SillyTavern and Discord's discontinued Clyde. It can be used as a practical assistant, customizable companion, and role-play partner for yourself in DMs, or for everyone in your Discord server.

TomoriBot supports long-term memory, multi-persona behavior, web and MCP tools, in-chat media generation, 100+ Discord slash commands, and multiple providers including custom proxies and self-hosting your own models for everything from text generation to video generation.

You can invite the public TomoriBot to your Discord server, or self-host your own instance if you prefer full control over your privacy and API keys. TomoriBot uses best security practices and encryption that keeps data safe, but self-hosting ensures that all data remain entirely on your device.

After adding her to your server through either method above, run the /config setup command for instructions. Then you can simply say her name (or @ mention her) in order to get a response.

If you're enjoying TomoriBot, please consider giving her a ⭐ on GitHub or supporting development through Ko-fi!

Feature Showcase

Supported API Providers

TomoriBot supports a wide range of LLM providers, image generation APIs, voice services, and search tools out of the box. This includes popular providers like Google Gemini, OpenRouter, Anthropic, NovelAI, Nvidia, Deepseek, and more.

Read the full list of Supported Providers here

Local & Self-Hosted Endpoints

Besides APIs, you can also connect TomoriBot to your own self-hosted models. She supports local LLMs (via Ollama, KoboldCPP, LM Studio, vLLM, etc.), local image/video generation via ComfyUI, local TTS and STT endpoints, as well as local SearXNG and Browser web fetch Docker sidecars.

Read the Local & Self-Hosted Endpoints guide here

Security & Threat Models

TomoriBot employs encryption and security best practices to keep data and API keys completely safe (as well as your wallet through configurable per-member/server rate limits), giving you full control and privacy when self-hosting:

Read the full Security & Threat Models here

Tool Macros for Prompt Customization

TomoriBot comes with a variety of built-in tools (such as web search, memory management, image generation, cross-channel messaging, and more), which you can directly refer to in your prompts with macros:

Read the complete Built-In Tool Reference here

Sample Prompts with Tools

These are some short silly examples of the kind of system-prompt instructions that make good use of TomoriBot's tool chains in a Discord community. Of course, you can make it more practical by being more creative.

1. Weekly Current Events Yuri News

Every Friday, compile the week's notable yuri manga chapters, anime episodes, and community fanart drops using {web_search_tool}. 
Present findings with {voice_message_tool} in a seductive ASMR voice.

2. Wellness Checker

Every few hours, do a mandatory wellness check on @Bredrumb. 
Ask them how they feel right now and if they've taken a break from coding recently. 
Track their emotional state over time with {memory_tool} and/or {memory_update_tool} to report back to them later.

3. Sleep Police

If you notice through {message_metadata_tool} that someone is chatting past 2 AM, use {voice_message_tool} to send them a threateningly calm ASMR lullaby telling them to go to bed. 
If they keep talking 10 minutes later, use {manage_message_tool} to delete their message for their own good and remind them that sleep deprivation is a leading cause of their issues.

Self-Hosting

Choose one install path:

• A. Local Bun Setup (Recommended): requires Bun, Node.js v20+ for MCP tooling, and either PostgreSQL or Docker for the database.
• B. Docker Compose Setup: requires Docker only for running the bot/database, but host-side maintenance scripts still need host tooling.

The recommended path for most self-hosters is the local Bun setup wizard. Its default Full Install path creates .env, generates a safe CRYPTO_SECRET, asks for your Discord bot token, configures PostgreSQL, runs bun install --frozen-lockfile, then attempts the lightweight database and AI helper extras.

A. Local Bun Setup

1. Clone the repository

   git clone https://github.com/Bredrumb/TomoriBot.git
   cd TomoriBot
   

2. Run the setup wizard (more info at Setup Wizard guide)

   bun run setup
   

3. Start TomoriBot

   bun run dev
   

Once you see TomoriBot up and running!, run /config setup in Discord.

B. Docker Compose Setup

Docker Compose builds and runs TomoriBot plus PostgreSQL. It does not use the setup wizard.

Required .env variables for Docker Compose:

• DISCORD_TOKEN - Your Discord bot token
• CRYPTO_SECRET - 32-character encryption key
• POSTGRES_PASSWORD - Database password (other DB settings are auto-configured)

For Docker Compose, start from .env.example, then add POSTGRES_PASSWORD if you have not already set it. Optional Docker or runtime tuning values can still be copied from .env.optional.example.

# Build and start TomoriBot and her database
docker compose up --build

For later starts, docker compose up is enough unless you changed code or dependencies.

C. Optional Sidecars & Servers

TomoriBot supports opt-in sidecar/server services alongside either setup path to enhance her tools and add local monitoring: SearXNG for web search, Crawl4AI for browser-rendered page fetches, local TTS/STT voice servers, and Grafana dashboards.

With the local Bun setup (A), use bun run launch instead of bun run dev, example runs:

# With SearXNG and Crawl4AI Docker sidecars
bun run launch --searxng --crawl4ai

# With a local TTS server after following the voice setup docs
bun run launch --qwen3tts

# See all available flags
bun run launch --help

Available flags: --searxng, --crawl4ai, --qwen3tts, --chatterbox, --irodoritts, --whisperx, --help

Ctrl+C stops the bot and any Python sidecar processes. Docker containers (--searxng, --crawl4ai) are intentionally left running, stop them manually with docker stop searxng / docker stop crawl4ai when you're done.

With Docker Compose (B), sidecars are opt-in via Compose profiles instead:

# + SearXNG web search (self-hosted metasearch)
docker compose --profile searxng up

# + Crawl4AI browser-rendered page fetching
docker compose --profile fetch-crawl4ai up

# + Both at once
docker compose --profile searxng --profile fetch-crawl4ai up

See the guides below for full setup details:

• SearXNG Web Search Sidecar - A self-hosted metasearch instance to bypass single-engine API limits for the web_search tool.
• Crawl4AI Sidecar - A browser-rendering sidecar to fetch and process JavaScript-heavy webpages for the fetch_url tool.
• Text-to-Speech / Speech-to-Text - Python voice servers for TomoriBot's voice messages; their venv must be set up once beforehand.
• Local Grafana Monitoring - Instructions on how to spin up a local Grafana dashboard to monitor TomoriBot's performance and database metrics.

Updating TomoriBot

To update your self-hosted instance to the latest version, stop the bot first (so the backup and any migrations run against a quiet database), then run the backup-first updater:

bun run update

The command runs this sequence, stopping immediately if any step fails:

1. bun run backup - takes a full database backup before touching any code. If the backup fails, the update aborts with your deployment completely unchanged.
2. git pull --rebase --autostash
3. bun install --frozen-lockfile

Then restart TomoriBot with bun run dev or bun run launch

Useful flags:

The other host-side maintenance scripts (bun run backup, bun run restore-backup, bun run nuke-db, bun run rotate-keys, and more) and database backup/restore for both local and Docker Compose deployments are all documented, but do note that TomoriBot already automatically backs-up your data locally in /backups/.

After Inviting / Setup

Basic Commands

• /config setup - Initial bot setup for your server
• /config - Multiple ways to tweak TomoriBot
• /memory personal add / /memory personal remove - Add / remove your personal memories
• /memory server add / /memory server remove - Add / remove server-wide memories
• /server whitelist / /server user-blacklist - Add / remove permissions from TomoriBot

See the full Command Reference for every slash command.

Chat Interaction

Simply mention the bot in a server or use the configured trigger words to start a conversation:

@TomoriBot yo wassup

Or slide into TomoriBot's DMs and say hi!

Roadmap

• Core AI chat functionality
• Memory system implementation
• Slash command structure
• Multi-language Support (Locale system)
• Multiple Provider Support (Google, OpenRouter, NovelAI, Nvidia, Vertex AI, ZAI, Custom)
• Image Generation Capabilities
• Voice integration (ElevenLabs TTS/STT)
• SillyTavern card import and preset system
• Video Generation Capabilities
• TTS/STT Capabilities
• Full Local Model Support
• Knowledge graph memory system (Qdrant)
• TomoriBot Wiki (for local set-up and locale contributions)
• Replace AI-generated placeholder assets
• Web dashboard for configuration
• Create "easy install" file for non-technical users wishing to host their own TomoriBot

See the Official GitHub Project for a full list of proposed features and known issues.

Contributing

Since TomoriBot is still in Beta, any contributions made are greatly appreciated, especially for localization.

To contribute a new language translation:

1. Create a locale file in src/locales/ named after a Discord locale code (e.g., es-ES.ts for Spanish, fr.ts for French, ko.ts for Korean)

2. Mirror the structure of the gold standard file src/locales/en-US.ts:

   • Copy all keys and nested objects
   • Translate all user-facing text while preserving placeholders like {variable}

3. Add preset translations (optional but recommended) in src/db/seed/catalog/personas/:

   • For each persona folder (bratty/, default/, gloomy/, etc.), copy en-US.ts to {your-locale}.ts
   • Translate the desc, attributes, sampleDialoguesIn, and sampleDialoguesOut fields, and set language to your locale code
   • Add LLM descriptions by translating the ja field of each row in src/db/seed/catalog/models.ts (alongside the English desc); both personas and models are seeded into the database directly from these catalogs at startup (no SQL file to regenerate)

4. Test your translations:

   # Verify all locale keys match across files
   bun run check-locales
   

5. Submit a pull request with your new locale file(s) and any src/db/seed/catalog/ additions

To contribute new features

The TomoriBot wiki for contributors is still WIP, but comprehensive documentation is already available HERE. Please follow the Contributing Guidelines before opening a pull request. They cover branching, quality gate checks, and the scope of contributions welcomed without prior discussion.

Legal & License

For users of the official hosted TomoriBot instance:

• Terms of Service - Rules and guidelines for using the bot
• Privacy Policy - How we handle your data

These documents are also accessible within Discord using /legal terms and /legal privacy commands. If you're self-hosting TomoriBot, these documents serve as reference templates. You control of your own data and are responsible for your deployment's compliance under the GNU Affero General Public License v3.0.

Contact & Links

Official Website: https://docs.tomoribot.app

Project Link: https://github.com/Bredrumb/TomoriBot

Email: [email protected]

Discord: Official Support Server