RustFox — Telegram AI Assistant

A self-hosted, agentic Telegram AI assistant written in Rust, powered by OpenRouter LLM (default: moonshotai/kimi-k2.5) with built-in sandboxed tools, scheduling, persistent memory, and MCP server integration.

Features

• Telegram Bot — Responds only to configured user IDs
• OpenRouter LLM — Configurable model (default: moonshotai/kimi-k2.5)
• Built-in Tools — File read/write, directory listing, command execution (sandboxed)
• Scheduling Tools — Schedule, list, and cancel recurring or one-shot tasks
• Persistent Memory — SQLite-backed conversation history and knowledge base
• Vector Embedding Search — Hybrid vector + FTS5 search using qwen/qwen3-embedding-8b
• MCP Integration — Connect any MCP-compatible server to extend capabilities
• Bot Skills — Folder-based natural-language skill instructions auto-loaded at startup; orchestration and subagent skills (e.g. daily-news-to-threads) let the main agent delegate to specialized subagents and override models per task
• Agents Layer — Isolated agentic mini-loops in agents/ with their own model, tool whitelist, and AGENT.md instructions; invoked via invoke_agent, with read_agent_file/write_agent_file for file I/O and reload_agents for hot-reloading
• Plan Tools — plan_create, plan_update, plan_view built-in tools let the agent create and manage structured execution plans stored in the sandbox; power the problem-solver subagent skill
• Bundled Subagent Skills — code-interpreter (executes and iterates code snippets) and problem-solver (orchestrates multi-step reasoning with plan tools) ship out of the box
• Streaming Responses — LLM tokens streamed progressively; Telegram message is live-edited as the response arrives
• Chat History RAG — Semantically relevant past messages are auto-injected into each turn's system prompt using vector search
• RAG Query Rewriting — Ambiguous follow-up questions are rewritten before vector search for more accurate retrieval
• Nightly Summarization — LLM-based cron job summarizes long conversations overnight to keep memory efficient
• Verbose Tool UI — /verbose command toggles a live Telegram status message showing tool calls as they run
• Agentic Loop — Automatic multi-step tool calling until task completion (max iterations configurable, default 25)
• Per-user Conversations — Independent conversation history per user

Quick Start

1. Build

cargo build --release

2. Configure

Run the setup wizard — it guides you through all required fields and writes config.toml for you:

# Browser-based wizard (recommended)
./setup.sh

# Terminal wizard (no browser required)
./setup.sh --cli

The wizard will ask for your:

• Telegram bot token (from @BotFather)
• Allowed Telegram user IDs (from @userinfobot)
• OpenRouter API key (from openrouter.ai/keys)
• Sandbox directory, model, and optional MCP tools

Manual setup: Copy config.example.toml to config.toml and edit it directly if you prefer.

3. Run

cargo run --bin rustfox
# or with a custom config path:
cargo run --bin rustfox -- /path/to/config.toml

Configuration

See config.example.toml for all options.

Key Settings

MCP Server Configuration

RustFox supports the Model Context Protocol (MCP) — an open standard for connecting AI assistants to external tools and data sources. Any MCP-compatible server can be plugged in via config.toml.

Prerequisites

MCP servers are usually distributed as Python packages (run via uvx) or npm packages (run via npx).

Config Syntax

Add one [[mcp_servers]] block per server in config.toml:

[[mcp_servers]]
name   = "server-name"   # used to namespace tools: mcp_<name>_<tool>
command = "uvx"          # or "npx", or any executable on PATH
args   = ["package-name", "optional-arg"]

# Optional: pass environment variables to the server process
# [mcp_servers.env]
# API_KEY = "your-key-here"

Popular MCP Servers

Find more servers at the MCP server registry and mcp.so.

Examples

# Git — inspect repositories
[[mcp_servers]]
name    = "git"
command = "uvx"
args    = ["mcp-server-git"]

# Filesystem — expose an extra directory to the bot
[[mcp_servers]]
name    = "filesystem"
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

# Brave Search — web search (requires API key)
[[mcp_servers]]
name    = "brave-search"
command = "npx"
args    = ["-y", "@brave/brave-search-mcp-server"]
[mcp_servers.env]
BRAVE_API_KEY = "your-brave-api-key"

# Meta Threads — publish posts and read replies (requires long-lived access token)
# Token setup: Facebook Developers → Create App → add Threads API product →
#   request threads_basic / threads_content_publish / threads_manage_replies /
#   threads_read_replies → generate token under Threads API → Access Tokens
[[mcp_servers]]
name    = "threads"
command = "npx"
args    = ["-y", "threads-mcp-server"]
[mcp_servers.env]
THREADS_ACCESS_TOKEN = "your-long-lived-access-token"

Tool Naming

Tools from MCP servers are automatically namespaced as mcp_<server-name>_<tool-name> (e.g. mcp_git_git_log). Run /tools in the bot to see all registered tools after startup.

Built-in Tools

Core Tools

Scheduling Tools

Agent Tools

Plan Tools

Bot Commands

Architecture

src/
├── main.rs           # Entry point, config loading, initialization
├── config.rs         # TOML configuration parsing
├── llm.rs            # OpenRouter API client with tool calling
├── agent.rs          # Agentic loop, tool dispatch, scheduling tools; agents/ layer
├── tools.rs          # Built-in tools (file I/O, command execution, plan tools)
├── mcp.rs            # MCP client manager for external tool servers
├── memory/           # SQLite persistence, vector embeddings, RAG, query rewriter, summarizer
├── scheduler/        # Cron/one-shot task scheduler with DB persistence
├── skills/           # Skill loader (auto-loads from skills/ directory)
└── platform/         # Telegram bot handler

agents/               # Agent definition files (AGENT.md per agent)
skills/
├── code-interpreter/ # Subagent skill: execute and iterate code snippets
├── problem-solver/   # Subagent skill: multi-step reasoning with plan tools
└── creating-agents/  # Instruction skill: how to author new agents

Roadmap

Done

• Telegram bot with user allowlist
• OpenRouter LLM integration with tool calling (agentic loop)
• Built-in sandboxed tools (file read/write, directory listing, command execution)
• MCP server integration for extensible tooling
• Per-user conversation history
• Persistent memory with SQLite
• Vector embedding search (qwen/qwen3-embedding-8b)
• Scheduling tools (schedule_task, list_scheduled_tasks, cancel_scheduled_task)
• Bot skills (folder-based, auto-loaded at startup)
• Setup wizard (web UI + CLI) for guided config.toml creation
• Agent skill writer (write_skill_file tool — creates/updates skill files from within the agent)
• Agent skill reload (reload_skills tool — hot-reloads skill registry without restart)
• Meta Threads MCP integration (setup wizard entry, config example, token setup guide)
• Agents layer (invoke_agent, read_agent_file, write_agent_file, reload_agents — isolated agentic mini-loops in agents/ with own model and tool whitelist)
• Plan tools (plan_create, plan_update, plan_view — structured execution plans in the sandbox)
• Bundled subagent skills: code-interpreter and problem-solver
• LLM streaming (SSE token-by-token, live Telegram message edits)
• Chat history RAG (auto-inject relevant past context per turn)
• RAG query rewriting (disambiguates follow-up questions before vector search)
• Nightly conversation summarization (LLM-based cron job)
• Verbose tool UI (/verbose command — live tool call progress in Telegram)
• Google integration tools (Calendar, Email, Drive)

Planned

• Image upload support
• Event trigger framework (e.g., on email receive)
• WhatsApp support
• Webhook mode (in addition to polling)
• And more…

Contributing

This project is open source under the MIT License. Contributions are very welcome! See CONTRIBUTING.md for how to open issues and submit pull requests.

Support

If you find RustFox useful, consider supporting the project:

Dependencies

• teloxide — Telegram bot framework
• rmcp — Official MCP Rust SDK
• reqwest — HTTP client for OpenRouter
• tokio — Async runtime
• tokio-cron-scheduler — Task scheduling
• pulldown-cmark — Markdown parser (entity-based Telegram formatting)

Thanks: Markdown-to-entities conversion approach inspired by telegramify-markdown by sudoskys.