Skip to content
Atomic Agent logo Atomic Agent docs

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.

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-...).
  • 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:

Terminal window
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. If you’d rather configure it 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:

    Terminal window
    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. Pair as the owner. Message your bot and complete owner pairing. From then on, only your account is accepted.

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:

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

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.
  • Local models — the model Telegram drives.
  • Configuration — the .env secrets file and precedence rules.
  • Tools — the approval gate behind those inline buttons.