ollamabot

A maubot plugin that lets a Matrix bot chat using a self-hosted Ollama LLM, with optional web search via SearXNG.

Features

• Responds only when @mentioned or replied to — stays quiet otherwise.
• Stateless: each triggering message is sent to Ollama independently (no stored conversation history). If you reply to a message, that message's text is included as light context.
• Optional web search: the model can call a web_search tool backed by your SearXNG instance whenever it decides it needs current information. Requires a tool-calling-capable model (Llama 3.1+, Qwen 2.5+, Mistral, etc).
• Configurable allowlist, system prompt, generation options, and timeouts.

Requirements

• A running maubot instance.
• A reachable Ollama server with a model already pulled.
• (Optional, for web search) A SearXNG instance with JSON output enabled.

Building the plugin

This repo contains the plugin source, not a prebuilt .mbp. Build it yourself with the maubot CLI:

pip install maubot
mbc build

This produces ollamabot.mbp in the current directory, which you upload via the maubot management UI's Plugins tab. You can also build and upload directly to a running instance in one step:

mbc build --upload

Setup

1. Upload ollamabot.mbp in the maubot admin UI (Plugins tab).
2. Create a client for the bot's Matrix account (Clients tab). Use a fresh login (e.g. mbc auth) rather than a token copied from an E2EE-capable client like Element if you plan to use this in encrypted rooms.
3. Create an instance (Instances tab), selecting the client and the com.example.ollamabot plugin.
4. Configure the instance (see Configuration below).
5. Invite the bot to a room, then @mention it or reply to one of its messages.

Configuration

All options live in the instance's config editor in the maubot UI, seeded from base-config.yaml.

Key	Description
base_url	URL of your Ollama server, e.g. http://192.168.1.50:11434
model	Model name, must already be pulled on the Ollama server
system_prompt	Optional system prompt; blank ("") to disable
timeout	HTTP timeout (seconds) for Ollama requests
options	Passed through to Ollama as generation options (e.g. temperature)
allowlist	List of Matrix user IDs allowed to trigger the bot; empty = anyone
typing_indicator	Show a typing indicator while waiting on a response
reply_context_chars	Max characters of a replied-to message to include as context; 0 disables
web_search.enabled	Toggle web search on/off
web_search.searxng_url	Base URL of your SearXNG instance
web_search.max_results	Max search results fed back to the model per search
web_search.timeout	HTTP timeout (seconds) for SearXNG requests
web_search.max_tool_iterations	Max search-then-think round trips per message

Enabling JSON output on SearXNG

SearXNG's JSON API is disabled by default. In your SearXNG settings.yml:

search:
  formats:
    - html
    - json

Restart SearXNG after changing this. Verify with:

curl "http://your-searxng-url/search?q=test&format=json"

A 403 response means JSON output still isn't enabled.

Notes on encryption

If your rooms are encrypted (e.g. default rooms in Element X), maubot needs its own encryption-capable client session — you can't reuse an access token copied from Element or another E2EE client. See maubot's encryption docs and use mbc auth to log in fresh.

License

MIT