# RustFox

> A Rust-based Telegram AI assistant powered by OpenRouter LLM with built-in sandboxed tools, scheduling, persistent memory, and MCP server integration.

- **Type:** MCP server
- **Install:** `agentstack add mcp-chinkan-rustfox`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [chinkan](https://agentstack.voostack.com/s/chinkan)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [chinkan](https://github.com/chinkan)
- **Source:** https://github.com/chinkan/RustFox

## Install

```sh
agentstack add mcp-chinkan-rustfox
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/chinkan/RustFox/releases):

```bash
tar xzf rustfox-*.tar.gz
```

**Option B — Build from source**

```bash
cargo install --path . --locked
```

### 2. Configure

```bash
# 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

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

### 4. (Optional) Background service

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

---

## Configuration

| Setting | Description |
|---------|-------------|
| `telegram.bot_token` | Telegram Bot API token (from [@BotFather](https://t.me/BotFather)) |
| `telegram.allowed_user_ids` | Comma-separated user IDs allowed to use the bot |
| `openrouter.api_key` | OpenRouter API key ([openrouter.ai/keys](https://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](https://github.com/chinkan)
- **Source:** [chinkan/RustFox](https://github.com/chinkan/RustFox)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-chinkan-rustfox
- Seller: https://agentstack.voostack.com/s/chinkan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.