RustFox

RustFox — Telegram AI Assistant

[](https://github.com/chinkan/RustFox/actions) [](LICENSE) [](https://buymeacoffee.com/chinkan.ai) [](https://github.com/sponsors/chinkan)

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](README.md) · [GUIDE.md](docs/GUIDE.md) · [ARCHITECTURE.md](docs/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](docs/GUIDE.md#advanced-features)

Agent Lifecycle & Runtime

| Capability | Description | |------------|-------------| | Self-Upgrade | Trigger an in-place upgrade: pulls from git source or downloads the latest GitHub release binary. Auto-restarts after upgrade — no SSH, no manual steps. | | Model Switching | Switch OpenRouter models at runtime via /models. Interactive picker lets you choose the best model per task: fast/cheap for simple queries, powerful for complex reasoning. | | Soul Files | SOUL.md (persona), AGENTS.md (behaviour), USER.md (preferences) — persistent identity files auto-injected into every system prompt. Session-end self-reflection with .bak backups. |

---

💭 Multi-Session & Multi-Model (Brainstorming)

> ⚠️ Planning phase — not yet implemented. This section captures ideas explored in the feat/readme-improve-multi-session-brainstorm branch.

The vision: run multiple concurrent chat sessions, each with its own model and isolated context.

| Use Case | Description | |----------|-------------| | Parallel execution | Run a cheap model for quick tasks while a powerful model tackles deep analysis — concurrently, not sequentially | | Per-user isolation | Each Telegram user gets their own session with independent conversation context and model preference | | Sub-agent delegation | Spawn sub-agents with different models (e.g., GPT-4o for code review, Claude for writing) without polluting the main session |

Topics to explore:

• Session lifecycle — create, switch, merge, archive
• Per-session model binding vs global default model
• Context isolation between sessions (independent or shared RAG?)
• Telegram UX for multi-session management (inline buttons? slash commands?)
• Persistence and RAG across session boundaries

See [docs/roadmap/multi-session.md](docs/roadmap/multi-session.md) for detailed design notes.

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](docs/GUIDE.md#mcp-server-integration)) |

→ Full configuration reference: [docs/GUIDE.md](docs/GUIDE.md#configuration)

---

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](docs/GUIDE.md#built-in-tools)

---

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](docs/ARCHITECTURE.md)

---

Contributing

MIT License. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to open issues and submit PRs.

Support

[](https://buymeacoffee.com/chinkan.ai) [](https://github.com/sponsors/chinkan)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chinkan
• Source: chinkan/RustFox
• License: MIT

Install and usage instructions live in the source repository linked above.