Drive the agent from Telegram

Atomic Agent can be driven from your phone over Telegram. It’s the same agent and the same local model — the model still runs on your machine; Telegram is just a remote control. The channel is deliberately single-user: once paired, only the owner’s messages are accepted and everyone else is dropped.

Caution

The Telegram channel is inert by default. It does nothing until telegram.enabled is true and a bot token is present. If you don’t set it up, it stays off.

What you need

• A Telegram account.
• A bot token from Telegram’s @BotFather (create a bot, and it hands you a token that looks like 123456:ABC-...).
• Node.js 25.7.0 or newer.
• Atomic Agent installed and a local model running.

Set it up

The easiest path is the TUI. Open it and go to the Telegram panel:

atomic-agent tui

In the setup (Manage tab → Telegram, or the /telegram panel) you can pair an owner, set the token, and toggle the remote-control channel.

Pairing needs the TUI

Editing config.json alone can never pair you. Every DM is dropped while no owner is set, so messaging the bot before you open a pairing window does nothing at all. The window is opened from a running agent with /telegram pair — that is the only way to become the owner.

If you’d rather configure the rest by hand:

1. Enable the channel in config.json:

   {
     "telegram": { "enabled": true }
   }

2. Add your bot token to the secrets file at <stateDir>/.env (by default ~/.atomic-agent/.env) — never in config.json, because the token belongs in the secrets file, which is written with mode 0600:

   TELEGRAM_BOT_TOKEN=123456:ABC-your-bot-token

3. Restart the agent. A secret written to .env is picked up on the next start, not mid-session.

4. Open a pairing window. In the running TUI, type:

   /telegram pair

   This opens a 60-second window. It is not optional: until a window is open, the channel has no owner and drops every DM it receives.

5. DM the bot within those 60 seconds. Send it any message — /start works fine. The first eligible direct message that lands inside the window becomes the owner; the agent saves that account to telegram.ownerUserId and restarts the channel. From then on, only your account is accepted.

   If the window expires before you send anything, nothing is paired — run /telegram pair again. To hand the bot to a different account later, use /telegram clear-owner and pair again.

Using it

Once paired, just chat with the bot to send the agent a request — the same way you’d type in the TUI. When the agent wants to run a dangerous tool, execution pauses and an approval request arrives as inline approve / deny buttons; the tool only runs if you approve.

A few built-in commands:

/start, /help   show commands and setup
/status         active session, turn count, last error
/new            start a fresh session
/cancel         abort the running turn

Telegram has its own session

The channel keeps a separate session lineage from the TUI. Chatting from your phone doesn’t continue the conversation open on your desktop, and /new rotates only the Telegram side — the current session is archived and a fresh one starts, leaving the TUI untouched.

Text only — media is silently ignored

The bot handles exactly two kinds of update: text messages and approval button presses. Photos, voice notes, documents, stickers, and captioned media are dropped on the floor — no reply, no error, nothing in the chat to tell you it happened. Send your model a screenshot and it looks like the agent simply ignored you. If you want an image analysed, put it on the machine running the agent and ask for it by path.

Approvals expire

An approval request sent to Telegram auto-denies after 8 minutes if you don’t tap anything. That’s the away-from-keyboard policy: a pending tool call can’t wait indefinitely for a phone you left on a table. The window isn’t configurable.

Known rough edge: /cancel leaves stale buttons

If you /cancel a turn while an approval is still pending, the agent unwinds correctly — but the inline keyboard stays in the chat until that 8-minute timer runs out. Press one of those stale buttons and the toast cheerfully reports “Approved” or “Denied” for a decision that no longer applies to anything; the tool does not run either way. It’s a display wart rather than a safety hole — nothing executes behind your back — but don’t read that confirmation as proof something happened.

Two config keys worth knowing

Both live under telegram in config.json and both have sensible defaults, so you only touch them if something misbehaves:

Key	Default	Effect
parseMode	"html"	How agent replies are formatted. "html" converts the model’s markdown into Telegram’s HTML subset; "plain" disables formatting entirely — the escape hatch if the formatter mangles something
progressIndicator	true	The live “Thinking…” bubble that mirrors the turn’s activity and deletes itself when the reply lands. Set false to switch it off

{
  "telegram": {
    "enabled": true,
    "parseMode": "plain",
    "progressIndicator": false
  }
}

parseMode governs agent replies only. Command output (/help, /status, the cancellation acks) and approval prompts are always sent as plain text, so switching to "html" won’t add formatting there.

The /telegram commands

Bare /telegram opens the Telegram panel. Each verb below drives one step of the channel’s lifecycle from the editor:

Command	What it does
/telegram enable	Turn the channel on
/telegram disable	Turn it off
/telegram start	Start the bridge
/telegram stop	Stop the bridge
/telegram restart	Restart it — the usual fix after changing the token
/telegram pair	Open the 60-second owner-pairing window
/telegram token	Open the masked token prompt
/telegram clear-token	Delete the stored bot token
/telegram clear-owner	Forget the paired owner

The token never touches your shell history

/telegram token takes no argument. It only ever opens a masked prompt inside the TUI, so there is no form of this command that puts your bot token on a command line — nothing for your shell history, terminal scrollback, or a screen recording to capture.

clear-token and clear-owner are the revoke path. Use clear-token when a token may have leaked (revoke it in BotFather too, then set the new one), and clear-owner to hand the bot to a different account — after which you pair again.

Caution

Both clear commands take effect immediately, with no confirmation, and so do their panel equivalents: T clears the token and O clears the owner, one shift away from t (open the token prompt) and o (start pairing). See TUI panels.

Privacy and safety

• Single-user by design. Pairing binds the channel to one owner; messages from anyone else are dropped (it fails closed when no owner is set).
• The token never leaks. It lives only in .env (0600) and is scrubbed from error messages before they reach logs.
• Approvals still apply. Remote-driving doesn’t bypass the approval gate — risky tool calls wait for your explicit yes, from your phone.

Related

• Local models — the model Telegram drives.
• Configuration — the .env secrets file and precedence rules.
• Tools — the approval gate behind those inline buttons.