Latchkey Bot

A Matrix bot plugin for interacting with local LLM models through llama-swap.

Features

• Chat: Interactive conversations with configurable AI models
• Image Generation: Create images using Stable Diffusion or Flux models
• Web Search: Tool-enabled bot can search the web via SearXNG for current information
• Web Fetch: Retrieve and parse content from specific URLs
• Conversation History: Maintains context across messages per room/user pair

Requirements

• Maubot 0.1.0+
• llama-swap running locally or remotely
• Optional: SearXNG instance for web search functionality

Installation

Via Maubot Dashboard

1. Click "Install from URL" in your Maubot dashboard
2. Enter the URL to this repository or download the .mbp file
3. Configure the bot with your settings

Manual Installation

1. Build the plugin:

   pip install maubot
   maubot build
   

2. Upload com.devvul.latchkeybot-v*.mbp via Maubot dashboard or CLI

Configuration

Edit the config.yaml generated by Maubot or use base-config.yaml as reference:

# Only users on this list are allowed to use the bot
allowlist:
  - "@username:matrix.org"

# llama-swap backend URL
llama_swap_url: "http://localhost:8080"

# API key for llama-swap (leave empty for no auth)
api_key: ""

# Model to use for chat completions
chat_model: "qwen3.5"

# Model to use for image generation (used by !image)
image_model: "z-image"

# Model to use for flux image generation (used by !fluximage)
flux_image_model: "flux"

# System prompt for chat
system_prompt: "You are Latchkey, a helpful and concise chat assistant..."

# Max conversation context messages to retain per user per room
max_context_messages: 20

# Max tokens for chat completion responses
max_tokens: 1024

# Image generation size (e.g., "1024x1024")
image_size: "1024x1024"

# LoRA tag to append to flux image prompts (e.g., "<lora:lora:1.0>"), leave empty to disable
flux_image_lora: ""

# Enable tool use (web search, web fetch) in chat - requires searxng_url
tools_enabled: true

# SearXNG instance URL for web search tool (e.g., "http://localhost:8888")
searxng_url: ""

# Max tool call iterations per chat message before forcing a final response
max_tool_iterations: 5

Commands

Chat

!latchkey <message>      Chat with Latchkey
!latchkey reset          Clear conversation history
!slop <message>          Alias for !latchkey
!chat <message>          Alias for !latchkey

Image Generation

!image <prompt>          Generate an image using configured model
!latchkeyimage <prompt>  Alias for !image
!fluximage <prompt>      Generate an image using Flux model

How It Works

Chat Mode

1. User sends a message via command
2. Bot retrieves conversation history for the room/user pair
3. Messages are sent to llama-swap with optional system prompt
4. Response is streamed back and displayed to the user
5. Conversation history is updated

Tool-Enabled Mode

When tools_enabled is true and searxng_url is configured:

1. Bot sends messages with tool definitions (web_search, web_fetch)
2. Model can request tool calls in its response
3. Bot executes requested tools and appends results to context
4. Loop continues until model responds without tool calls or max iterations reached

Image Generation

1. User sends image generation command with prompt
2. Request sent to llama-swap /v1/images/generations endpoint
3. Base64-encoded image returned and decoded
4. Image uploaded to Matrix home server and sent to room