Talking to an agent in Telegram
Through Telegram you can ask an agent for work from your phone: “what changed in the project today”, “run the checks”, “prepare a fix”. But SHIPIT has no built-in connection between Telegram and an agent, and nobody turns one on for you.
The reason is simple. Telegram is an open channel, and an agent has access to your folder and your commands. So there are two honest paths: you do some of the steps yourself, or you give the agent access to the Telegram API yourself and take responsibility for the consequences.
Path 1. Do it yourself (the default)
Telegram only receives messages from programs the agent wrote for you: notifications, reminders, replies to customers. You give the agent its tasks in SHIPIT, where you see everything at once and where it asks for confirmation.
| What you do | What the agent does |
|---|---|
| Create the bot in @BotFather and get the token. | Writes the bot, or a script that writes to you in Telegram. |
| Open the bot and press Start. | Checks that messages arrive. |
Put the token in .env, not in a chat. | Reads the token from .env and does not print it. |
| Give tasks in SHIPIT and confirm risky actions. | Does the task and sends you the result in Telegram. |
This is the safest way and it is enough for most jobs: the agent works, and you learn the result on your phone.
Path 2. At your own risk: give the agent the Telegram API
If you want to write to the agent straight from Telegram, you can hand it your bot’s token. Then the agent itself calls the Telegram Bot API: it reads new messages from your chat and replies there. This is not a SHIPIT feature but ordinary network work by the agent.
What you take on
- The token is a password to the bot. Now the agent sees it, and everything the agent sees in a session goes to the company behind that agent (see the data section of the first-run guide). If the token becomes known, generate a new one with
/tokenin @BotFather. - Only you. The agent must accept messages only from your chat id and ignore everyone else. Otherwise anyone who finds the bot can steer the agent, and through it your Mac. This rule matters more than all the others.
- There are no confirmations in Telegram. In SHIPIT the agent asks permission for risky actions. You cannot answer such a question from the phone: either it waits for you, or, if you allowed everything beforehand, it acts without asking. Do not allow everything.
- You are responsible for the agent’s actions, including those given from your phone. Read Agent Risk & Acceptable Use.
Why SHIPIT has to be open
The agent works on your Mac
If you close the lid or switch the Mac off, the agent does not answer: nobody is there. Telegram keeps messages that nobody has picked up for no more than 24 hours, and then they disappear. So the Mac must be on, online and not asleep. Turn off automatic sleep in the macOS energy settings for as long as you need this.
In sync means one folder and one history
SHIPIT shows the same folder, the same files and the same Git history the agent works with. An open SHIPIT lets you see what the agent did through the chat, and what you changed in SHIPIT the agent sees when you write to it. A closed SHIPIT breaks nothing, but you see the work only when you open it again.
How to do it
01Create the bot and put the details in .env
This is described step by step in the first bot guide. In the project folder, .env must hold the token and your chat id. Do not paste the token into the agent chat: write it into the file yourself.
02Tell the agent what is allowed and what is not
Open the project in SHIPIT and write, for example:
This folder has TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in .env. Read new Telegram messages through the Bot API, but only from this chat id; ignore everyone else. Reply to me in the same chat and split long answers into several messages. You may read files, explain things and prepare changes on a separate Git branch. Do not publish, delete or make payments. Never print the token in your answers.
03Start with a safe task
Write the bot something like “show what changed in the project”. Check that the answer comes only to you, and try writing to the bot from another account: the agent must not reply.
What SHIPIT does and does not do
SHIPIT has no “connect Telegram to the agent” button and no separate place for the token. Everything you do here is ordinary agent work with files and commands in your folder. Start with reading and preparing changes rather than full access, and add permissions only when you understand why.
Can I run several projects this way
Yes, but it is simpler to have one bot per project: each has its own folder, its own permissions and its own token. Projects do not get mixed up, and you can revoke access one at a time.