Your loyal AI harness — command your computer from anywhere.
Features · How it works · Demo · Getting started · Plugins · Examples · Roadmap
Vassal is an AI-powered remote-control assistant for your own computer. Tell it what you want — by voice or text, from anywhere — and it carries out real actions on your machine: managing your notes, checking your GitHub, reading and writing files, looking things up, and much more. It runs on your hardware and works for you while you're away from the keyboard.
You command it through a messenger — Telegram today, with more on the way — so your computer is one message away wherever you are.
It acts through MCP — small add-ons you switch on for whatever you need. Thousands of ready-made MCPs already exist — for GitHub, files, the web, calendars, and far more — so Vassal can do a huge range of things out of the box. It works out which ones to use and runs them for you, step by step, until the job is done.
You stay in control: it runs on your hardware, and only the accounts you approve can reach it. The AI model behind it is your choice — run one locally (with LM Studio, Ollama, …) to keep everything on your machine, or connect to an online provider for more capable models.
- 🖥️ Remote control — drive your own computer from anywhere; it does the work at home while you're away.
- 🧩 Thousands of MCP tools — plug in capabilities (GitHub, files, the web, …); add and toggle them at runtime.
- 🎙️ Voice or text — type or speak; voice is transcribed locally with Whisper.
- 🧠 Any LLM — runs against any OpenAI-compatible model, local (LM Studio, Ollama) or remote.
- 🗂 Sessions — save and reload named conversation contexts.
- 📝 Memory — add or remove facts for Vassal to remember; they persist across sessions and are injected into the prompt.
- 🔒 Private & gated — it runs on your hardware, and only the accounts you approve can reach it.
You, from anywhere (text / voice)
│
▼
┌───────────┐ ┌──────────────┐
│ Vassal │ ───▶ │ MCP Plugins │ ───▶ Your Computer
│ (harness) │ ◀─── │ (tools) │
└─────┬─────┘ └──────────────┘
│
LLM (local or remote)
- Your message arrives over a messenger (Telegram today); voice is transcribed with Whisper.
- Vassal runs an agentic loop against your LLM, which decides which tools to call.
- The matching MCP tool executes the action, results are fed back into the loop, and Vassal replies once the task is done.
A few real use-cases with Vassal over Telegram:
Read your notes — "show today's daily note" pulls it straight from Obsidian.
Voice commands — send a voice message; it's transcribed locally and acted on (a task gets marked done).
Browse files — "show all daily notes" lists what's available.
Check your GitHub — summarize today's work across a repository.
Work with files — find a note on your Desktop and print its contents.
🚀 Thousands of MCP servers. Infinite possibilities.
The only limit is your imagination.
Requirements: Python 3.13+, uv, a Telegram bot
token (via @BotFather), and access to an OpenAI-compatible LLM
API — either local (LM Studio, Ollama, …) or a remote provider.
# clone
git clone git@github.com:CrazyProger1/Vassal-Assistant.git
cd Vassal-Assistant
# install dependencies
uv sync
# create your config from the template
cp settings.toml.example settings.tomlConfigure settings.toml with your bot token, the chat IDs allowed to use the bot,
and your LLM endpoint (local or remote):
[communication.telegram]
bot_token = "your-token"
chat_ids = ["your-chat-id"]
[llm]
model = "google/gemma-4-e2b"
api_base = "http://localhost:1234/v1"
api_key = "dummy"
context_window = 32000
max_output_tokens = 64000
max_steps = 10
[mcp]
file = ".mcp.json"
[files]
assets_directory = "./assets"
prompts_directory = "./assets/prompts"
downloads_directory = "./assets/downloads"
sessions_directory = "./assets/sessions"
memories_file = "./assets/memories.json"
[files.prompts]
base = "base.jinja2"
task = "task.jinja2"Before the first run, compile the translation catalogs — the bot fails to start without the
.mo files:
make i18n.compileThen run uv run python __main__.py and message your bot. Send /help to open the menu.
Note: The first run can take a while — the Whisper model used for voice transcription is downloaded on startup.
You can also run Vassal in a container. The image compiles the translation catalogs for you:
make docker.build
make docker.rundocker.run mounts settings.toml, .mcp.json, and assets/ from the repo, so your
configuration stays on the host and the downloaded Whisper model is cached across restarts.
Equivalent raw command:
docker build -t vassal:latest .
docker run --rm -it \
-v "$PWD/settings.toml:/app/settings.toml" \
-v "$PWD/.mcp.json:/app/.mcp.json" \
-v "$PWD/assets:/app/assets" \
vassal:latestNote: stdio MCP servers run as subprocesses inside the container, so any commands they invoke must be available in the image.
/start,/help,/menu— show the main menu/sessions— save or load a named conversation/clear— clear the current context/mcp— list, add, toggle, or replace MCP servers/memory— add or remove things for Vassal to remember
Vassal is built around the Model Context Protocol (MCP). Each capability is an MCP
server declared in .mcp.json, so you can add new skills without touching the core.
Servers can be listed, added, toggled on/off, and reconfigured at runtime from the
/mcp menu in Telegram.
{
"mcpServers": {
"time": {
"command": "uvx",
"args": [
"mcp-server-time"
]
}
}
}Here you can find real-life examples of Vassal in action, ready to copy and run:
- Obsidian Assistent — read notes, check off tasks, and query your daily notes from Telegram.
- GitHub Assistent — check what changed, read issues and pull requests, and query repos from Telegram.
- 💬 More messengers — reach Vassal through other platforms, starting with Discord and WhatsApp.
- 🖼️ Image input — send photos and screenshots as part of a request.
- 🖥️ Local operation — talk to Vassal directly on your machine, by voice and by text, without going through a messenger.