RustFox — Telegram AI Assistant

A self-hosted, agentic Telegram AI assistant written in Rust, powered by OpenRouter LLM (default: moonshotai/kimi-k2.6) 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.6)
• 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
• Persistent Home Directory — All state under ~/.rustfox (config, DB, skills, agents, workspace); override via RUSTFOX_HOME env or [general].home config
• Autopilot Supervisor — Generic autonomous task runner with classification, planning, multi-backend execution, verification, and approval gates; /supervise to submit tasks
• LangSmith Tracing — Optional observability via LangSmith for LLM calls, tool runs, and chain traces
• Post-task Learning — Auto-extracts reusable skill patterns from completed agentic loops; persists honcho-style user model
• Skill/Agent Update Engine — Content-hash diffing with lock files; /update-skills re-syncs bundled skills/agents with backup of local edits
• Instance + Bundled Layering — Skills and agents load from two directories (instance shadows bundled); bundled templates ship with the project

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

Persistent home: RustFox keeps all state under ~/.rustfox by default (config, database, skills, agents, and a durable workspace/ sandbox). Override with the RUSTFOX_HOME environment variable or [general].home. See docs/persistent-home-directory.md.

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.6)
sandbox.allowed_directory	Directory for file/command operations
memory.database_path	SQLite DB path (default: <home>/rustfox.db)
memory.user_model_path	User model file path (default: <home>/user_model.md)
memory.query_rewriter_enabled	Whether RAG query rewriting is on by default
embedding (optional)	Vector search API config (default model: qwen/qwen3-embedding-8b)
skills.directory	Instance (writable) skill files (default: <home>/skills/)
skills.bundled_directory	Bundled (read-only) skill templates (default: ./skills/)
agents.directory	Instance (writable) agent files (default: <home>/agents/)
agents.bundled_directory	Bundled (read-only) agent templates (default: ./agents/)
mcp_servers	List of MCP servers to connect
general.home	Absolute path overriding ~/.rustfox home root
general.location	Your location string (under [general]), injected into system prompt
agent.max_iterations	Max agentic loop iterations (default: 25)
langsmith.api_key	LangSmith API key for LLM observability
learning.skill_extraction_enabled	Post-task skill extraction on/off
supervisor.default_autonomy_mode	Supervisor workflow mode: fast, standard, rigorous

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:

# Stdio-based server
[[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"

# HTTP/Streamable HTTP server (omit command for this transport)
# [[mcp_servers]]
# name       = "api-server"
# url        = "https://api.example.com/mcp"
# auth_token = "bearer-token-here"

# OAuth 2.0 refresh flow (auto-exchanges refresh_token for new auth_token)
#   token_endpoint  = "https://api.example.com/oauth/token"
#   refresh_token   = "your-refresh-token"
#   token_expires_at = <unix-timestamp>

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

Skill Tools

Tool	Description
read_skill_file	Read a file from a skill's directory (loads skill instructions)
write_skill_file	Write new or update existing skill files
reload_skills	Hot-reload the skill registry without restarting the bot

Agent Tools

Tool	Description
invoke_agent	Run an agent from the agents/ directory in an isolated agentic loop
invoke_subagent	Alias for invoke_agent (backward compat)
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
reload_skills_and_agents	Reload both registries in one call

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 with command list
/clear	Clear conversation history
/tools	List all available tools
/skills	List all loaded skills
/verbose	Toggle live tool call progress display
/query-rewrite	Toggle RAG query rewriting for memory search
/update-skills	Re-sync bundled skills/agents (backs up local edits)
/supervise <text>	Submit a new supervisor task
/tasks	List active / recent supervisor tasks
/resume <id>	Resume a paused supervisor task
/cancel <id>	Cancel a supervisor task
/approve <id>	Approve a task that requires approval
/clarify <id> <text>	Reply to a clarification prompt

Architecture

src/
├── main.rs           # Entry point, config loading, initialization
├── config.rs         # TOML configuration parsing (Telegram, OpenRouter, sandbox, memory, skills, agents, langsmith, learning, supervisor)
├── home.rs           # Persistent home directory resolution (~/.rustfox)
├── llm.rs            # OpenRouter API client with tool calling
├── agent.rs          # Agentic loop, tool dispatch, scheduling tools; skills/agents/ layer
├── agent_prompt.rs   # Prompt preparation, message assembly, recovery nudges
├── 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, registry, seeding, update engine (loader.rs, mod.rs, seed.rs, update.rs)
├── learning.rs       # Post-task skill extraction, user model persistence
├── langsmith.rs      # Optional LangSmith observability client
├── supervisor/       # Autopilot v2 generic autonomous task runner
│   ├── mod.rs        # Supervisor facade (submit, execute_now, pause, resume, state, artifacts)
│   ├── task.rs       # Task, TaskType, RiskLevel, ExecutionMode, TaskStatus enums
│   ├── job.rs        # Job, JobType, JobStatus, JobOutput, Evidence
│   ├── state.rs      # Transition-allowed state machine
│   ├── store.rs      # CRUD over sup_tasks / sup_jobs / sup_transitions
│   ├── intake.rs     # IntakeRouter — raw text → Task normalization
│   ├── classifier.rs # Heuristic / LLM-backed / Skill-aware classifiers
│   ├── policy.rs     # PolicyEngine — auto-execute, clarify, require approval
│   ├── planner.rs    # Task → Plan with jobs and parallel groups
│   ├── workflow.rs   # Fast / Standard / Rigorous workflow templates
│   ├── orchestrator.rs  # Plan executor with fallback + parallel + subjobs
│   ├── verification.rs  # Evidence-gated verification engine
│   ├── artifact.rs   # ArtifactManager with secret redaction
│   ├── workspace.rs  # Per-task git worktree management
│   ├── reporter.rs   # Human-readable job summary
│   ├── redact.rs     # Secret scrubber for api_key / password / token / bearer
│   └── backend/      # Backend implementations (reasoning, shell, MCP, claude-code, codex, script)
├── platform/         # Telegram bot handler (telegram.rs + tool_notifier.rs)
└── utils/            # String utilities, markdown-to-entities conversion

skills/               # Bundled skills (15+): code-interpreter, problem-solver, coding-assistant,
│                     #   soul, soul-keeper, memory-manager, creating-skills, creating-agents,
│                     #   news-fetcher, codebase-gap-analysis, sup-* workflow skills
agents/               # Agent definition files (AGENT.md per agent)
setup/                # Setup wizard HTML

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)
• Persistent home directory (~/.rustfox with env/config override)
• Autopilot v2 supervisor (classification, planning, multi-backend execution, verification)
• LangSmith observability (LLM/tool/chain tracing)
• Post-task skill extraction (auto-learns reusable patterns)
• User model persistence (honcho-style user_model.md)
• Skill/agent content hash engine + lock-file re-sync
• Instance + bundled skills/agents layering

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)
• rusqlite — SQLite with FTS5 and sqlite-vec
• axum — Web server for the setup wizard
• dirs — OS home directory resolution
• sha2 — SHA-256 hashing for skill/agent update engine
• regex — Secret redaction in supervisor artifacts

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