FreppeBot Documentation

Everything you need to know about setting up, configuring, and extending FreppeBot.

Introduction

FreppeBot is a self-hosted AI assistant framework. Unlike hosted solutions, you control everything: the AI model, the data, and the functionality.

Key features:

• Multi-model support - Connect to OpenAI, Anthropic, Kimi, or 100+ models via OpenRouter
• Plugin architecture - Extend functionality with simple JavaScript files
• Persistent memory - SQLite database stores conversations and user preferences
• Multi-platform - Works on Discord and Telegram out of the box
• Security features - Rate limiting, command cooldowns, and input validation
• Health monitoring - Track performance, system resources, and bot status
• Automatic backups - Database backups every 6 hours with manual controls
• Robust error handling - Graceful error recovery with helpful user messages

Installation

Requirements: Node.js 18+ and npm.

git clone https://github.com/freppebot/freppebot.git
cd freppebot
npm install

Run the interactive setup wizard:

npm run setup

This creates config.json with your AI provider keys, platform tokens, and bot personality.

Start the bot:

npm start

Configuration

All settings are stored in config.json. The setup wizard generates this file, but you can edit it manually.

Bot Settings

Platform Settings

Plugin Settings

AI Settings

How It Works

FreppeBot has a modular architecture with four main components:

1. Core Engine

The FreppeBot class in src/core/bot.js orchestrates everything. It initializes the database, AI manager, plugin loader, and platform adapters.

2. Message Router

When a message arrives, the router (src/core/router.js) decides how to handle it:

• If it starts with the command prefix, it looks for a matching plugin command
• Otherwise, it sends the message to the AI along with available tools
• When the AI calls a tool, the router executes it and returns the result

3. AI Manager

The AI manager (src/ai/manager.js) abstracts different AI providers. It handles message formatting, tool call parsing, and provider-specific quirks.

4. Plugin System

Plugins provide commands (user-invoked) and tools (AI-invoked). The loader scans plugins/ folders and registers everything automatically.

5. Utilities

Additional utilities provide essential functionality:

• Rate Limiter - Prevents abuse with per-user request limits
• Cooldown Manager - Enforces delays between command executions
• Health Monitor - Tracks bot performance and system metrics
• Backup Manager - Handles automatic and manual database backups
• Input Validator - Sanitizes and validates user input

AI Providers

FreppeBot supports multiple AI backends:

Set your preferred provider in config.json under ai.defaultProvider.

Platform Adapters

Adapters connect FreppeBot to messaging platforms.

Discord

Uses Discord.js. Requires a bot token from the Discord Developer Portal.

Telegram

Uses node-telegram-bot-api. Get a token from BotFather.

Both adapters normalize messages into a common format before passing them to the router.

Plugin System

Plugins are the primary way to extend FreppeBot. Each plugin can provide:

• Commands - User-triggered actions (e.g., !weather tokyo)
• Tools - Functions the AI can call automatically

Plugins live in two folders:

• plugins/core/ - Essential plugins (memory, reminders, web fetch)
• plugins/community/ - Optional plugins (weather, crypto, spotify, etc.)

Core Plugins & Commands

These plugins are always loaded and provide essential functionality:

Built-in Commands

Built-in Core Plugins

These plugins are part of FreppeBot core and are always loaded. They cannot be disabled.

Community Plugins

These plugins are included with FreppeBot but are optional. They can be disabled via plugins.disabled in config.json. Located in plugins/community/.

Note: Community plugins can be disabled by adding their name to plugins.disabled array in config.json.

Create a Plugin

Create a new file in plugins/community/:

// plugins/community/hello.js
const { Plugin } = require('../../src/plugins/sdk');

module.exports = new Plugin({
    name: 'hello',
    description: 'A simple greeting plugin',
    version: '1.0.0',

    // Commands are triggered by users
    commands: {
        greet: {
            description: 'Greet someone',
            handler: async (ctx, args) => {
                const name = args[0] || 'friend';
                return `Hello, ${name}!`;
            },
        },
    },

    // Tools are called by the AI
    tools: {
        sayHello: {
            description: 'Greet a person by name',
            parameters: {
                name: { 
                    type: 'string', 
                    description: 'Name to greet' 
                },
            },
            execute: async (params, ctx) => {
                return { 
                    message: `Hello, ${params.name}!` 
                };
            },
        },
    },
});

After saving, the plugin auto-loads (if hot reload is enabled) or loads on next restart.

Plugin Manager

FreppeBot includes a plugin manager (similar to npm) for downloading and managing plugins from URLs.

Installation

Use the plugin manager via npm scripts:

npm run plugin <command>

Or install globally to use the freppe command:

npm install -g .
freppe <command>

Download Plugins

Download and install plugins from URLs:

# From raw GitHub file
npm run plugin download https://raw.githubusercontent.com/user/repo/main/plugin.js

# From GitHub blob URL (auto-converted)
npm run plugin download https://github.com/user/repo/blob/main/plugin.js

# Force overwrite existing plugin
npm run plugin download <url> --force

The plugin manager automatically:

• Normalizes GitHub URLs to raw content URLs
• Validates the plugin before installation
• Extracts plugin name and metadata
• Tracks the source URL for future updates

List Plugins

View all installed plugins:

npm run plugin list

Shows plugin name, version, description, installation date, and source URL.

Remove Plugins

Uninstall a plugin:

npm run plugin remove <plugin-name>

This removes the plugin file and updates the metadata.

Update Plugins

Update a plugin to the latest version from its original URL:

npm run plugin update <plugin-name>

The plugin manager remembers the original URL and re-downloads from it.

Plugin Validation

Before installation, plugins are validated to ensure:

• Valid JavaScript syntax
• Exports a Plugin instance
• Has required fields (name, description)
• Can be loaded without errors

Metadata Storage

Plugin metadata is stored in plugins/community/.freppe-plugins.json:

• Original download URL
• Plugin version
• Installation timestamp
• Plugin description

This metadata enables features like automatic updates and source tracking.

Security Features

FreppeBot includes multiple layers of security to protect your bot and prevent abuse:

Rate Limiting

Prevents API abuse and cost spikes by limiting requests per user:

• Default limit: 10 requests per minute per user
• Admin exemption: Admins bypass rate limits
• Clear feedback: Users see helpful messages when limits are reached

Rate limits are tracked per user and reset automatically after the time window expires.

Command Cooldowns

Prevents command spam and accidental duplicate executions:

• Default cooldown: 2 seconds between commands
• Shell commands: 5 second cooldown (prevents dangerous rapid execution)
• Reminder commands: 3 second cooldown
• Configurable: Cooldowns can be customized per command

Input Validation

All user input is validated and sanitized before processing:

• Length limits: Messages limited to 10,000 characters
• Sanitization: Removes null bytes and dangerous characters
• Type checking: Tool arguments validated against parameter schemas
• Parameter validation: Required parameters checked, types verified

Access Control

Fine-grained access control for commands and features:

• User whitelist: Restrict bot to specific users (empty = allow all)
• Admin users: Separate list of users with elevated privileges
• Admin-only commands: Dangerous operations require admin status
• Tool permissions: Plugins can mark tools as admin-only

Error Handling

Secure error handling that protects system information:

• User-friendly messages: Errors shown to users don't expose internals
• Detailed logging: Full error details logged for debugging
• Graceful degradation: Bot continues operating even when errors occur
• Stack traces: Available in debug mode for developers

Health Monitoring

FreppeBot includes comprehensive health monitoring to track bot performance and system status.

Health Command

Use !health or !status to view a detailed health report:

!health

The health report includes:

• Bot Status: Uptime, start time, overall health
• Adapters: Connection status for Discord/Telegram
• Statistics: Messages processed, commands executed, errors encountered
• Database: Message count, user count, memory entries, pending reminders
• System Resources: CPU usage, memory usage, disk space
• Plugins: Number of loaded plugins

Tracked Metrics

The health monitor automatically tracks:

Use Cases

• Debugging: Check if adapters are connected properly
• Performance: Monitor message throughput and error rates
• Resource Management: Track memory and CPU usage
• Status Checks: Verify bot is running and healthy

Database Backups

FreppeBot automatically creates backups of your database to prevent data loss.

Automatic Backups

The bot creates backups automatically:

• Frequency: Every 6 hours
• Location: data/backups/
• Format: freppebot-backup-YYYY-MM-DDTHH-MM-SS.db
• Retention: Last 10 backups kept automatically

Backups are created silently in the background and don't impact bot performance.

Manual Backups

Create a backup on demand using the backup command:

!backup

This creates an immediate backup and shows you the filename and size.

Backup Management

List all available backups:

!backup list

This shows all backups with their sizes and creation dates.

Delete a specific backup (admin only):

!backup delete freppebot-backup-2024-01-01T12-00-00.db

Restoring Backups

To restore from a backup:

1. Stop the bot
2. Copy the backup file to data/freppebot.db
3. Restart the bot

Backup Best Practices

• Keep backups in a separate location for disaster recovery
• Test restore procedures periodically
• Monitor backup directory size
• Create manual backups before major updates

Docker Deployment

FreppeBot includes a Dockerfile and docker-compose.yml for easy deployment.

Quick Start

# Build and run
docker compose up -d

# View logs
docker compose logs -f

# Stop the bot
docker compose down

Volume Mounts

Make sure to mount your configuration and data directories:

volumes:
  - ./config.json:/app/config.json
  - ./data:/app/data

This ensures your configuration and database persist across container restarts.

Environment Variables

You can also use environment variables for configuration (see docker-compose.yml for details).

Production Deployment

For production deployments, consider:

• Using Docker secrets for API keys
• Setting up log rotation
• Configuring health checks
• Using a reverse proxy for additional security
• Regular backup verification

Troubleshooting

Common issues and their solutions:

Bot Not Responding

If the bot isn't responding to messages:

1. Check health status: Run !health to see adapter connection status
2. Check logs: Review data/freppebot.log for errors
3. Verify API keys: Ensure your AI provider API key is valid in config.json
4. Check permissions:
   • Discord: Ensure bot has "Send Messages" and "Read Message History" permissions
   • Telegram: Ensure bot is started and token is correct
5. User whitelist: If allowedUsers is set, ensure your user ID is included

Rate Limit Errors

If you see rate limit messages:

• Wait for cooldown: The message shows how long to wait
• Admin exemption: Add your user ID to adminUsers to bypass limits
• Adjust limits: Edit src/utils/ratelimit.js to change limits (requires restart)

Command Cooldown Messages

If commands are on cooldown:

• Wait for the cooldown period shown in the error message
• Admins can have cooldowns reset (feature can be added to admin commands)
• Cooldowns prevent accidental duplicate commands

Database Issues

If you encounter database errors:

1. Check file exists: Ensure data/freppebot.db exists
2. Check permissions: Bot needs read/write access to data/ directory
3. Check disk space: Ensure sufficient disk space for database operations
4. Restore from backup: Use a backup if database is corrupted
5. View database stats: Use !health to see database size and stats

Plugin Not Loading

If a plugin isn't working:

1. Check file location: Plugin must be in plugins/core/ or plugins/community/
2. Check syntax: Ensure JavaScript syntax is valid
3. Check disabled list: Verify plugin isn't in plugins.disabled array
4. Check logs: Look for plugin loading errors in data/freppebot.log
5. Hot reload: If hot reload is enabled, changes should apply automatically
6. Restart bot: Sometimes a full restart is needed

AI Provider Errors

If AI responses fail:

• Check API key: Verify API key is correct and not expired
• Check quota: Ensure you haven't exceeded API rate limits or quotas
• Check model: Verify the model name is correct for your provider
• Check network: Ensure bot can reach the AI provider's API
• Try different provider: Switch to a different provider to test

Memory/Reminder Issues

If memories or reminders aren't working:

• Check database: Use !health to verify database is working
• Check timezone: Reminders use system timezone
• Check permissions: Ensure bot can write to database

Getting Help

If you're still having issues:

• Check logs: Review data/freppebot.log for detailed error messages
• Enable debug mode: Set bot.logLevel to debug for more verbose logging
• Health report: Run !health and share the output
• GitHub Issues: Open an issue on GitHub with logs and configuration (redact API keys!)