Lux

Matrix bot AI agent powered by OpenAI-compatible LLMs.

Note: This is experimental software. Not production-ready.

Setup

1. Copy .env.example to .env and fill in your credentials:

HOMESERVER=https://matrix.org
MATRIX_USERNAME=@yourbot:example.org
MATRIX_PASSWORD=your_password
ADMINS=@admin:example.org

2. Build and run:

cargo run

The bot will log in, store session data in data/, and begin listening for messages.

3. Create a provider inside the bot

Add an LLM provider to the system using an admin account.

Usage

In Matrix rooms, the bot responds to whitelisted users. Use # commands for control:

#status              - Show bot status
#model <id> [provider] - Set LLM model
#provider add <name> <base_url> [api_key] - Add LLM provider
#whitelist add <user> - Allow user to chat
#memories            - List stored memories
#help                - Show all commands

Only admins can run # commands. Regular whitelisted users can just chat.

Configuration

Variable	Description
HOMESERVER	Matrix homeserver URL
MATRIX_USERNAME	Bot login
MATRIX_PASSWORD	Bot password
ADMINS	Comma-separated admin Matrix IDs
WHITELISTED_USERS	Initial whitelisted users (comma-separated)
CROSS_SIGNING_RECOVERY_KEY	Matrix cross-signing recovery
ENABLE_BACKUP	Enable Matrix key backup

Data directory (data/) contains session tokens, database, and encrypted Matrix state. It's gitignored.