Install and set up
Your own agent in Telegram
in ten minutes
One command on a server or a computer. The installer downloads the ready-made program, the wizard asks for the model and the bot, checks everything itself and starts the agent as a service.
Current version v1.2.4. A Linux server works, and so does a computer running Windows or macOS.
Video guide
Installation in a minute and a half
A real recording on a clean Debian server. The slow parts are sped up. The AI key and the bot token in the recording are test ones. The voice-over is in Russian, but the commands are the same as in this guide.
Before you start
What you need
A server or a computer
A Linux server is best: the agent then answers around the clock. Ubuntu or Debian, an x86_64 or arm64 processor, 2 GB of memory or more, and SSH access with root rights. For transcribing voice notes and call recordings 4 GB and 4 cores are better. You do not need to open any ports to the outside: the agent picks up messages from Telegram itself. For Windows and macOS see below.
Access to a model
A ChatGPT subscription (you sign in with a code from your phone, no key needed) or an API key: OpenRouter, DeepSeek, Anthropic, GigaChat, YandexGPT and others. A model of your own on the same machine works too.
A Telegram bot
Message @BotFather, send /newbot, and pick a name and a username for the bot. BotFather sends back a token: a long string with a colon in it. You will paste it into the wizard.
Your own Telegram ID
This is the number by which the agent recognises its owner. Message @userinfobot and it will send you your ID. If you did not get to it, the bot will tell you the ID itself in reply to your first message.
Step by step
Installation
# on the server, as root# curl -fsSL https://capyagent.com/install.sh | sh
Log in to the server
Open a terminal and connect: ssh root@server_address. If you log in as an ordinary user, become root with sudo -i.
Run one command
The installer downloads the ready-made program for your processor from capyagent.com, checks the checksum and opens the setup wizard by itself. There is nothing to build.
Choose a model
Enter a number from the list or a name: chatgpt, openrouter, deepseek. For a ChatGPT subscription the wizard shows a link and a code: open the link on your phone and enter the code. For an API key, paste it and press Enter. The wizard checks right away that the model answers, and only then writes the settings.
Connect Telegram
Paste the bot token (it is not shown as you paste, that is by design) and your Telegram ID. When asked about the service, answer "yes": the agent will then run by itself and come back up after a reboot. If you want voice notes and call recordings, answer "yes" to those questions too. Files over 20 MB need the server to reach Telegram directly, and servers in Russia usually cannot: in that case answer "no" to that question, everything else works anyway.
Write to the bot
Wait for the final line saying the agent now runs as a service ("Готово: агент работает службой") and write "hello" to the bot in Telegram. The agent will answer. After that just talk to it.
Your own computer
Windows and macOS
The agent also runs on an ordinary computer. The Telegram bot answers while the computer is on and the agent is running. If you need a bot that works around the clock, put it on a server.
macOS
Open Terminal and run the same command as on the server: curl -fsSL https://capyagent.com/install.sh | sh. No administrator rights are needed: the program goes into your home folder and the setup wizard opens by itself. At the end the wizard prints the exact command that starts the agent: while it runs, the bot answers. Transcribing voice notes on a Mac needs the whisper.cpp program: brew install whisper-cpp.
Windows
Open PowerShell (not as administrator) and run: iwr -useb https://capyagent.com/install.ps1 | iex. The program goes into your user profile and the wizard asks for the model and the bot the same way as on a server. Transcribing voice notes on the machine itself is not available on Windows yet. If you have WSL2 with Ubuntu, you can install the agent inside it with the Linux command.
The app with a window
If you would rather not use a terminal, download the CapyAgent app for macOS, Windows or Linux. It is the same agent inside: the chat, the settings and the Telegram connection in a window.
Afterwards
Useful commands
For a Linux server and an install done as root. If you installed as an ordinary user, the program is in ~/.local/bin/capyagent and the service is managed through systemctl --user.
# check that everything is in order# /opt/capyagent/bin/capyagent doctor # is the agent running, and its log# systemctl status capyagent# journalctl -u capyagent -f # update by hand# /opt/capyagent/bin/capyagent update
What the agent does right away: answers in Telegram and in the web panel, remembers conversations, transcribes voice notes and call recordings right on the server, accepts large files, and sets reminders and scheduled jobs.
If it did not work
Frequent questions
The wizard says the service does not let you in from your country
The bot does not answer
/opt/capyagent/bin/capyagent doctor: it shows what is wrong and suggests what to do. The service log: journalctl -u capyagent -f. A common cause: the bot answers only if you wrote from the Telegram account whose ID you gave the wizard.How to update the agent
sudo CAPYAGENT_UPDATE=1 /opt/capyagent/bin/capyagent update. Before updating it saves the previous version and your data, and rolls back if something fails.Can I install without root, or on my own computer
Do voice notes and call recordings go anywhere
How much does it cost
The agent is running - give it its first job
You can work it out yourself or order a setup for your tasks.