Vusan

Vusan is a Telegram AI agent for private chats and groups, currently in alpha — breaking changes may occur between updates.

Try it live in the Vusan Playground Telegram group.

Highlights

• Code execution — runs Python in an isolated sandbox: exact math, file transforms, charts, and animations.
• Vision — understands photos and image documents.
• Voice in and out — transcribes voice messages and replies with generated speech.
• Scheduled tasks — the bot acts on its own later: once, on an interval, or on a cron schedule.
• Durable memory — per-user and per-group memory that survives chat-history clears.
• And more — web search, GIFs, YouTube video/audio, currency rates, native polls and quizzes, reactions.

See features.md for the full list.

Stack

Built on Koog — JetBrains' Kotlin agent framework — with ktgbotapi for Telegram and Exposed/SQLite for storage. Works with OpenAI, Anthropic, Google, DeepSeek, or any OpenAI-compatible server — see configuration.md.

For a tour of the layers and how a message flows through them, see architecture.md.

Quick start

Clone the repo and enter the project directory:

git clone https://github.com/Helltar/vusan.git
cd vusan

Copy the env template:

cp .env.example .env

Only a few values are required to start (see minimum setup); everything else is optional:

ALLOWED_IDS=123456789,-1001234567890
TELEGRAM_BOT_TOKEN=1234567890:qwerty
LLM_PROVIDER=openai
LLM_MODEL=gpt-5.4-mini
LLM_API_KEY=sk-proj-qwerty

Docker

Use the published images:

docker compose up -d

This starts two containers: the bot and the code-execution sandbox. To run without the sandbox, see code execution.

Or build from source:

docker compose -f compose.yaml -f compose.local.yaml up --build -d

Local JVM

Prerequisites: JDK 21, plus ffmpeg and yt-dlp on PATH.

./gradlew run

./gradlew shadowJar produces a fat JAR at build/libs/vusan-<version>-all.jar.