Vusan

Vusan is an AI agent that lives in Telegram and is at its best in a group. It follows the conversation, knows who said what, remembers yesterday, and joins in like one more member. In a private chat it works the same, and everywhere it picks its own tools: search, code, voice, images, and more.

Try it live in the Vusan Playground Telegram group.

Quick start

The bot runs from its published image, so it needs only the compose file and the env template:

mkdir -p vusan/data && cd vusan && curl -fsSLO \
  "https://github.com/Helltar/vusan/raw/master/{compose.yaml,.env.example}" && \
  mv .env.example .env

Only these values in .env are required to start; everything else is optional and covered in configuration.md:

OWNER_ID=123456789
TELEGRAM_BOT_TOKEN=1234567890:qwerty
LLM_PROVIDER=openai
LLM_MODEL=gpt-6.1-sol
LLM_API_KEY=sk-proj-qwerty

Then start it:

docker compose up -d

That starts the bot, which is the whole deployment. Two capabilities stay off until it can reach a Regolith server: the sandbox shell, which runs model-authored commands, and publishing to the web, which puts what was built there at a public address. Both come from that one server, which is a separate project with a machine of its own as the recommendation.

Add it to a group

Add the group's ID to ALLOWED_IDS, then let the bot see the whole chat: turn off its privacy mode in @BotFather with /setprivacy, or make it an administrator. Without that Telegram shows it only mentions, replies and commands, so it can neither recap the chat nor answer to its name. More in Rights in a group.

From source

To build the image yourself or run on a local JVM, clone the repository and set up .env the same way:

git clone https://github.com/Helltar/vusan.git && cd vusan && \
  cp .env.example .env && mkdir data

Then build and start the image:

docker compose up --build -d

Or run it on JDK 21, with ffmpeg and yt-dlp on PATH:

./gradlew run

Features

At home in a group

• Called by name — answers when you say its name or follow up, no mention needed.
• Speaks up on its own — now and then reacts to a message, drops a line or a sticker without being called, and notices when someone has gone quiet.
• What the group said — recaps the whole conversation and answers questions about who said what.
• Diary — writes down what each day in a group was like and picks up yesterday's thread.
• Each person apart — keeps everyone's conversation, memory and sandbox their own in one chat.
• Replies — uses the message you reply to as context, including other people's files and pictures.
• Private replies — moves the answer into your DMs when you ask.
• Stickers — learns your chat's sticker collection and picks fitting replies from it.
• Forum topics — answers, notices and scheduled reminders stay in the topic they belong to.

Understands what you send

• Photos — answers questions about images you send or reply to.
• Voice and audio — listens to voice messages and audio files.
• Videos — understands videos, video notes and GIFs, including speech.

Looks things up

• Web search — searches the web and reads the pages it finds.
• Links — reads a web page you send and answers from it.
• Image search — finds pictures on the web and sends them.
• Telegram channels — recaps public channel posts by day or week, searches by keyword, and reads memes and screenshots.
• YouTube video and audio — finds videos by name or link and sends the video or audio track.
• YouTube transcripts — summarizes videos and answers questions using their subtitles.

Creates

• Its own sandbox — runs code, builds projects, converts media and analyzes data, then sends the results. Each person gets a private Linux home that persists across chats, and the bot edits what it built there in place rather than rewriting it.
• One job, many tools — passes what one tool made to the next, like voicing your video in its own voice with itself in the frame.
• Keeps you posted — says what it is about to do before a long job, and sends a first working version or a finding worth knowing while the rest is still in progress.
• Web pages — puts a page, game or small app it built on the internet at your own address, and hands you the link.
• Images — draws from descriptions, edits your pictures, and merges several into one.
• Voice replies — answers out loud with voice messages.
• Round video messages — replies with its own face and voice in a video circle.
• GIFs, memes and clips — finds a fitting GIF, meme picture or short clip, or makes a GIF from your video.

In the chat

• Live progress — shows what it is doing, and says what it is about to make before a long job.
• Stop button — ends a running answer from the progress message, in groups too.
• Inline choices — asks for decisions or confirmation with buttons and continues when you tap.
• Edits — answers when you add its mention to an earlier message.

Speaks Telegram

• Reactions — sometimes an emoji on your message is the whole answer.
• Polls and quizzes — creates Telegram polls and quizzes, and follows who answered what in a quiz.
• Files and links — sends documents, downloads links, and retrieves files behind chat stickers and pictures.
• Long structured answers — formats longer replies with headings, tables, and checklists.

Remembers

• Conversation history — keeps context with recent messages and recaps, separately in each chat.
• Sense of time — notices gaps between conversations.
• Memory — remembers facts about you and the group across history resets; forgets them on request.
• Scheduled tasks — runs tasks once or on a recurring schedule; lets you pause, resume, edit or cancel.
• Follow-ups — checks back after an exam, interview or other event you mentioned.

Documentation

• Configuration — every setting, from the required five onward.
• The sandbox shell — what the persistent home does, and how to deploy it.
• Publishing to the web — how a page built in the sandbox gets an address.
• Architecture — the layers, and how a message flows through them.

Stack

Kotlin, with TelegramBots for Telegram, Exposed/SQLite for storage, and its own thin clients for the OpenAI and Anthropic APIs. Works with OpenAI, Anthropic, any OpenAI-compatible server (DeepSeek among them), or a ChatGPT subscription instead of a paid API key — see configuration.md.