How to run your own AI assistant on Telegram

A step-by-step guide to a self-hosted AI assistant you talk to in Telegram: it runs on your machine, uses the model you choose, remembers what you tell it, and can post scheduled reports to a chat. About fifteen minutes from start to first message.

Griffin on GitHub Quick start

What you need

A machine that stays on: a small VPS, a home server or a Raspberry Pi-class box with Docker or Node.js 24.
An API key for Claude, or OpenAI, or any OpenAI-compatible server — including a local model (see running agents on a local LLM).
A Telegram account, to create a bot with @BotFather.

1. Start Griffin

docker run -d --name griffin -p 3100:3100 -v griffin-data:/data \
  -e ANTHROPIC_API_KEY=sk-ant-… ghcr.io/paziresh24/griffin:latest
docker exec griffin cat /data/owner.token   # the token you sign in with

Open http://your-server:3100 and sign in with the token. Put Griffin behind HTTPS (a reverse proxy such as Caddy or nginx) before you expose it to the internet.

2. Create a Telegram bot

In Telegram, open @BotFather, send /newbot, choose a name and a username, and copy the token it gives you.

3. Connect the bot to Griffin

In Griffin go to Settings → Integrations → Telegram bot and paste the token. Griffin shows a pairing command such as /start 4F7K2Q; send it to your bot. The bot replies that the chat is connected, and from then on everything you write to it reaches your agent.

/new starts a fresh conversation.
/stop stops the work in progress.
Photos you send reach the agent too; charts and files come back as images and attachments.

4. Make it yours

Go to Agents to change what the assistant is: its instructions, its model, and its tools. The repository ships a ready-made personal assistant profile (examples/agents/assistant.json) that keeps notes and turns recurring requests into scheduled jobs; import it and edit the instructions to taste.

5. Get a scheduled report in the chat

Just ask in Telegram: “every Monday at 9, send me a summary of last week”. The agent creates a job; you can also create one under Jobs → New job with a prompt, a schedule (an interval like 1d or a cron expression) and the chat to deliver to. Schedules follow your server's time zone, or GRIFFIN_TZ.

Optional: your own Telegram account

Instead of — or next to — a bot, Griffin can sign in to your own Telegram account (Settings → Integrations → Telegram account). Then you talk to it in Saved Messages by starting a message with “Griffin”, it can read groups you're in when you ask, and, optionally, colleagues' direct messages can open a work thread that the agent answers within the limits you set. Signing in an account is more powerful than a bot, so read the permissions guide first.

Keeping it safe

Only paired chats reach the agent; a stranger messaging your bot gets nothing.
Anything irreversible waits for your approval button in the chat.
Your keys and conversations stay on your server; Griffin has no hosted control plane.

Griffin is open source (MIT): github.com/paziresh24/Griffin.