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

Setting	Description
telegram.bot_token	Telegram Bot API token
telegram.allowed_user_ids	List of user IDs allowed to use the bot
openrouter.api_key	OpenRouter API key
openrouter.model	LLM model ID (default: moonshotai/kimi-k2.5)
sandbox.allowed_directory	Directory for file/command operations
memory.database_path	SQLite DB path (default: rustfox.db)
embedding (optional)	Vector search API config (default model: qwen/qwen3-embedding-8b)
skills.directory	Folder of bot skill files (default: skills/)
agents.directory	Folder of agent definition files (default: agents/)
mcp_servers	List of MCP servers to connect
general.location	Your location string (under [general]), injected into system prompt

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).

Runtime	Install
uvx (Python)	Install uv — curl -LsSf https://astral.sh/uv/install.sh | sh
npx (Node.js)	Install Node.js — comes bundled with npm/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

Server	Package	Runtime	Notes
Git	mcp-server-git	uvx	Read/search git repos
Filesystem	@modelcontextprotocol/server-filesystem	npx	File access outside the sandbox
Brave Search	@brave/brave-search-mcp-server	npx	Web search (needs Brave API key)
GitHub	@modelcontextprotocol/server-github	npx	Issues, PRs, repos
Fetch	mcp-server-fetch	uvx	HTTP fetch / web scraping
SQLite	mcp-server-sqlite	uvx	Query local SQLite databases
Puppeteer	@modelcontextprotocol/server-puppeteer	npx	Browser automation
Threads	threads-mcp-server	npx	Publish/manage Meta Threads posts (needs access token)

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

Tool	Description
read_file	Read file contents within sandbox
write_file	Write/create files within sandbox
list_files	List directory contents within sandbox
execute_command	Run shell commands within sandbox directory

Scheduling Tools

Tool	Description
schedule_task	Schedule a recurring (cron) or one-shot task with a message
list_scheduled_tasks	List all active scheduled tasks
cancel_scheduled_task	Cancel a scheduled task by ID

Agent Tools

Tool	Description
invoke_agent	Run an agent from the agents/ directory in an isolated agentic loop
read_agent_file	Read a file from within an agent's directory
write_agent_file	Write a file into an agent's directory
reload_agents	Hot-reload the agent registry without restarting the bot

Plan Tools

Tool	Description
plan_create	Create a new structured execution plan (stored as .rustfox_plan.json in the sandbox)
plan_update	Update a step's status or notes in the current plan
plan_view	View the current plan and its step statuses

Bot Commands

Command	Description
/start	Show welcome message
/clear	Clear conversation history
/tools	List all available tools
/verbose	Toggle live tool call progress display

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.