Build a Telegram Bot That Runs Your Mac

The split is the whole idea. A bot running on your laptop can do things no cloud service can — read your files, take a webcam photo, quit an app, shut the machine down — but it dies the moment the lid closes for good. A bot running on Cloudflare can answer at 3am from anywhere, but it has no idea what a Mac even is. Run both, on two separate tokens, and you stop having to choose.

What follows is the full command surface of a working setup, then how each half is deployed and why neither costs anything.

How each half is deployed

The local bot: long polling on the machine

A Python script using python-telegram-bot, running on the Mac. It uses long polling: it opens an outbound connection to Telegram and waits. Nothing listens on an open port, so there is no public IP to expose, no port forwarding, and no firewall hole. The machine reaches out; the internet never reaches in. That single design choice removes most of the attack surface a self-hosted bot would otherwise have.

Cost is zero. Telegram's Bot API is free and unmetered at this scale. The only thing consumed is the machine's own electricity.

brew install imagesnap ffmpeg
/usr/bin/python3 -m pip install --user \
  "python-telegram-bot[job-queue]" Pillow openai-whisper

Launching is a double-click on a .command file, which is just a shell script macOS opens in Terminal. Three things are worth building into that launcher:

1. Locate the script relative to itself with cd "$(dirname "$0")", so the project folder can be moved without breaking anything.
2. Probe for a working Python rather than trusting python3 from PATH.
3. Restart on crash, by wrapping the run in a while true loop with a short sleep, so a dropped network connection does not end the day.

The second point is the one that bites people. A Mac with Homebrew typically has at least two Python installs — Homebrew's at /opt/homebrew/bin/python3 and Apple's at /usr/bin/python3 — and your libraries are installed into exactly one of them. PATH usually resolves plain python3 to Homebrew's, which may not be the one holding your dependencies, and the bot dies on ModuleNotFoundError. Probing sidesteps the whole question:

PY=""
for c in /usr/bin/python3 /opt/homebrew/bin/python3 python3; do
    if command -v "$c" >/dev/null 2>&1 && \
       "$c" -c "import telegram" >/dev/null 2>&1; then
        PY="$c"; break
    fi
done

To start it on boot: System Settings → General → Login Items → add the .command file. Have the bot message you on startup, so you know it came back up.

The limitation that justifies a second bot: polling needs a running machine. A sleeping Mac queues commands and runs them on wake, since Telegram holds updates for 24 hours, but a powered-off Mac cannot answer at all. No setting fixes that — the process has to be running somewhere else.

The cloud bot: a Cloudflare Worker

The second bot is a Worker: a small piece of JavaScript that Cloudflare runs on its edge network, on demand, with no server to maintain. It uses webhooks instead of polling — Telegram sends an HTTP request to the Worker whenever a message arrives, and the Worker answers. Between messages nothing runs and nothing is billed.

Two pieces support it:

• Workers KV, a key-value store holding reminders, lists, notes and preferences, so state survives between invocations.
• A cron trigger firing every minute, which wakes the Worker to check whether a reminder is due or the digest should go out.

A once-a-minute cron costs 1,440 invocations a day against a 100,000 ceiling, so the headroom is enormous. The one real constraint is that writes are capped at 1,000 a day, which is why the scheduled handler should only write back to KV when something actually changed — not on every tick. Cron granularity also bottoms out at one minute, so a reminder can land up to sixty seconds late.

The outside services involved — wttr.in for weather, frankfurter.app for exchange rates — are free and need no API key.

Deploying the Worker

1. Create a second bot with @BotFather and copy its token. Use a separate bot from the local one, so the two never compete for the same updates.
2. Create a Worker in the Cloudflare dashboard and paste in the source.
3. Add TELEGRAM_TOKEN and a self-invented WEBHOOK_SECRET as encrypted secrets, not plain variables.
4. Create a KV namespace and bind it to the Worker under a name the code expects.
5. Add a cron trigger of * * * * *.
6. Register the webhook, passing the same secret:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook\
?url=https://<your-worker>.workers.dev\
&secret_token=<YOUR_WEBHOOK_SECRET>"

Roughly fifteen minutes end to end. The Worker can be served from a subdomain of your own domain instead of the default workers.dev address, though that is cosmetic.

Project layout

Security worth building in from the start

This is remote-control software by design. It reads files, watches through the camera, listens through the microphone, and can power the machine down. That reach is the point, and it also means your Telegram account becomes as sensitive as your login password. Four things are worth doing on day one:

• Lock both bots to one user ID. Check the incoming Telegram user ID against a single allowed value and ignore everything else. Enforce it twice in the local bot — once through a handler-level filter and again inside each function — so a newly added command cannot accidentally ship without a guard.
• Verify the webhook. Telegram will send your secret header on every webhook call; reject anything that does not carry it. Without that check, the Worker's URL is an open endpoint anyone can post to.
• Keep tokens out of the source. In the Worker, use encrypted secrets. The local script will realistically hold its token in plain text, which is normal for a file that never leaves your machine — but it makes that file one you must never paste into a chat, a gist, or a screenshot. If a token is ever exposed, /revoke in BotFather issues a new one in seconds.
• Turn on two-step verification for the Telegram account itself. Every control above assumes that account is yours alone.