--- title: "Controlling My Home Server From Telegram With Claude Code" date: 2026-03-20 draft: false description: "How I set up Claude Code's Telegram channel integration to manage my home server from my phone — and cleaned up some unused Docker containers while testing it out." tags: ["Claude Code", "AI", "self-hosting", "Telegram", "homelab", "automation"] --- I run a home server called **rocklab** — Ubuntu 24.04, a pile of Docker containers, and [Claude Code](https://claude.ai/code) acting as my on-call IT department. It handles routine maintenance, helps me publish blog posts, and executes whatever tasks I throw at it. The one missing piece was mobility. If I wanted to check on something or kick off a task, I had to be at a terminal. That changed today when I set up **Claude Code Channels** — specifically the Telegram plugin — which lets me message my server from anywhere and have Claude respond like a proper remote assistant. Here's how it works and how I set it up. --- ## What Are Claude Code Channels? Channels are a research preview feature in Claude Code (v2.1.80+) that let external events push into a running Claude session. Instead of only responding when you type something at the terminal, Claude can react to messages arriving from outside — Telegram, Discord, or whatever channel plugin you've configured. The architecture is simple: 1. You run Claude Code with `--channels plugin:telegram@claude-plugins-official` 2. A small Bun-powered MCP server listens for incoming Telegram messages 3. When a message arrives, it's injected into your Claude session 4. Claude processes it, runs whatever tools it needs, and replies back via Telegram It's bidirectional, and it feels surprisingly natural — just like texting, except the other end of the conversation can restart your Docker containers. --- ## Prerequisites Before setting this up, you'll need: - **Claude Code v2.1.80+** — check with `claude --version` - **Bun runtime** — the channel plugins are Bun scripts; install with `curl -fsSL https://bun.sh/install | bash` - **A claude.ai login** — Channels require claude.ai authentication, not API key auth - A Telegram account --- ## Step 1: Create a Telegram Bot Open Telegram and start a chat with **[@BotFather](https://t.me/BotFather)**. Send `/newbot`, give it a display name and a unique username ending in `bot`. BotFather will hand you a token that looks like: ``` 123456789:AAHfiqksKZ8WnHOmBabc123xyz ``` Hold onto that — it's how Claude Code authenticates with Telegram's API. --- ## Step 2: Install the Plugin and Configure the Token In your Claude Code terminal, install the plugin: ``` /plugin install telegram@claude-plugins-official ``` Then configure it with your token: ``` /telegram:configure ``` This saves your token to `~/.claude/channels/telegram/.env`. You can also set `TELEGRAM_BOT_TOKEN` as an environment variable if you prefer. --- ## Step 3: Pair Your Telegram Account Restart Claude Code with channels enabled: ```bash claude --channels plugin:telegram@claude-plugins-official ``` Now DM your bot on Telegram with any message. It'll reply with a 6-character pairing code. Back in Claude Code, run: ``` /telegram:access pair ``` Your Telegram user ID is now on the allowlist. To lock things down so only you can message the bot: ``` /telegram:access policy allowlist ``` Non-approved senders are silently dropped, so you don't have to worry about strangers poking at your server. --- ## What It Looks Like in Practice Once it's running, you just... text your bot. Today I used it to: **Check container status:** > "Can you see what Docker containers are currently running?" Claude ran `docker ps`, formatted the results, and sent back a clean list of all 15 containers with their uptime. Took about 5 seconds. **Remove unused services:** > "I'm not using any of the paperless containers, can you get rid of them?" Claude confirmed what it was about to do, asked whether to keep the data, and once I said "get rid of everything" — took down all three paperless-ngx containers (app, postgres, redis), removed the Docker network, and cleaned up the `/home/rock/paper` directory including a root-owned subdirectory that needed a container trick to delete. Done. That kind of task used to require SSH-ing in from my phone, navigating to the right directory, and running compose commands. Now it's a text message. --- ## A Few Things Worth Knowing **You're still in control of permissions.** If Claude hits a tool that requires approval and you're not at the terminal, it'll wait. For fully unattended operation you can use `--dangerously-skip-permissions`, but I'd only recommend that in a trusted environment where you understand the implications. **No message history.** The bot only sees messages as they arrive — there's no way to fetch past conversations through the API. If you need context from an earlier session, you'll have to paste it in. **Photos work.** Send an image and Claude downloads it locally and can read it. Telegram compresses photos by default; long-press and "Send as File" if you need the original. **It's a research preview.** The `--channels` flag syntax may change as the feature matures. Keep an eye on the Claude Code changelog. --- ## Why This Is Actually Useful The real value isn't novelty — it's removing friction from tasks I already do. Checking on a container, verifying a service is up, cleaning out something I'm not using anymore: these are all things I'd normally do at the terminal. Now I can do them from my couch or while I'm out. For homelab folks managing servers remotely, this is a genuinely practical addition to the toolkit. Give it a try. --- *Rocklab runs Ubuntu 24.04 with Docker, Cloudflare Tunnels, and Claude Code as the IT department. Posts like this document how things get built and changed on this server.*