RustFox — Telegram AI Assistant

What is RustFox?

An open-source, self-hosted Telegram AI assistant written in Rust. It solves a simple problem: most AI assistants are locked inside proprietary chat UIs with no access to your files, tools, or schedule. RustFox lives in Telegram — your everyday messaging app — and acts as a full agentic AI teammate.

Why RustFox?

Drop a file, ask a question, schedule a task — RustFox handles it. Powered by OpenRouter LLM (Kimi K2.6), it runs an agentic loop: receive your message, call sandboxed tools (file I/O, command execution, web search via MCP), and loop until done. It remembers context via SQLite + vector RAG, runs skills and sub-agents, and even verifies its own work.

Self-hosted, no cloud dependency. Single binary. Setup wizard. Runs as systemd/launchd service. cargo install and you're running in 2 minutes.

Star the repo ⭐, fork to contribute, or open an issue for feedback.

docs: README.md · GUIDE.md · ARCHITECTURE.md

---

Features

🤖 AI Agent	OpenRouter LLM (default: moonshotai/kimi-k2.6), agentic loop with tool calling, configurable max iterations
🔧 Built-in Tools	File read/write, command execution, file sending, task scheduling — all sandboxed
🧩 MCP Servers	Connect any MCP-compatible server (Git, Brave Search, GitHub, Filesystem, Threads…)
🧠 Persistent Memory	SQLite-backed conversation history, vector embedding search (hybrid + FTS5), RAG
🧬 Skills & Agents	Folder-based skill instructions auto-loaded at startup; subagent skills with own model and tool whitelist
🤝 Agent Layer	Isolated agentic mini-loops in agents/ with own model/tools; invoke_agent, spawn_agents, zero-trust verifier
🔄 Task Scheduling	Cron and one-shot task scheduler with SQLite persistence
📦 Self-Hosting	Single binary, 2-min setup wizard, background service (systemd/launchd/Windows Service)

→ Full feature reference: docs/GUIDE.md

---

| 🚀 Self-Upgrade | /self-upgrade slash command + self_upgrade tool, auto-restart after upgrade, git source or GitHub release binary | | 🔀 Model Switching | /models slash command to switch OpenRouter LLM models at runtime, with interactive model picker | | 📝 Soul Files | SOUL.md / AGENTS.md / USER.md persistent identity files, auto-injected into system prompt, session-end reflection with .bak backups |

Quick Start

1. Install

Option A — Download a release (recommended)

Download from the Releases page:

tar xzf rustfox-*.tar.gz

Option B — Build from source

cargo install --path . --locked

2. Configure

# Browser wizard
./rustfox --setup

# Or terminal wizard
./rustfox --setup --cli

The wizard guides you through: Telegram bot token, allowed user IDs, OpenRouter API key, model, and optional MCP tools.

3. Run

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

4. (Optional) Background service

rustfox --service install   # Linux (systemd), macOS (launchd), or Windows
rustfox --service status

---

Configuration

Setting	Description
telegram.bot_token	Telegram Bot API token (from @BotFather)
telegram.allowed_user_ids	Comma-separated user IDs allowed to use the bot
openrouter.api_key	OpenRouter API key (openrouter.ai/keys)
openrouter.model	LLM model ID (default: moonshotai/kimi-k2.6)
sandbox.allowed_directory	Directory for sandboxed file/command operations
mcp_servers	List of MCP servers to connect (see GUIDE.md)

→ Full configuration reference: docs/GUIDE.md

---

Quick Tool Overview

Tool	Description
read_file / write_file	Read and write files within the sandbox
send_file	Send a file from the sandbox to the current chat
self_upgrade	Trigger self-upgrade from git source or GitHub release, auto-restart
read_soul_file	Read SOUL.md, AGENTS.md, or USER.md soul files
update_soul_file	Append or replace content in a soul file with .bak backup
revert_soul_file	Restore a soul file from its most recent .bak backup
try_new_tech	Sandboxed experiment — run Rust/JS code and check results
execute_command	Run shell commands within the sandbox
schedule_task	Schedule recurring (cron) or one-shot tasks
invoke_agent	Run a predefined agent from the agents/ directory

→ Full tool reference: docs/GUIDE.md

---

Architecture

RustFox runs an agentic loop: user message → LLM (OpenRouter) → tool calls → execute → loop until final response. Tools dispatch to built-in functions, MCP servers, or skill/agent directories.

→ Full architecture with source tree and data flow: docs/ARCHITECTURE.md

---

Contributing

MIT License. See CONTRIBUTING.md for how to open issues and submit PRs.

Support