# OpenCode Telegram Bot: run coding tasks from your phone, with the OpenCode server staying on localhost

> grinev/opencode-telegram-bot is a TypeScript Telegram client for the OpenCode CLI. It connects out to your local OpenCode API on port 4096, so nothing is exposed inbound, and it adds scheduled prompts, session tracking and permission buttons.

**grinev/opencode-telegram-bot** — OpenCode mobile client via Telegram: run and monitor AI coding tasks from your phone while everything runs locally on your machine. Scheduled tasks support.

- Repository: https://github.com/grinev/opencode-telegram-bot
- Stars: 1,208 · Forks: 220
- Language: TypeScript
- License: MIT
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/grinev-opencode-telegram-bot

## What problem the OpenCode Telegram Bot solves

Long agent runs are boring to watch. You start a coding task in the OpenCode CLI, walk away, and come back to find it asked a clarifying question twenty minutes ago and has been idle since. The bot moves that supervision loop into Telegram: prompts go out from the phone, results come back as messages, and code comes back as files. The README frames the target user as someone already running OpenCode locally who wants remote control without opening a port. That constraint shapes everything else. The bot is a client, not a server. It dials the local OpenCode API, and it dials the Telegram Bot API, and it accepts nothing inbound. If you do not already use OpenCode, this project has no standalone value. It is an interface layer, and the README says so plainly by listing OpenCode as a prerequisite alongside Node.js 22.14+ and a Telegram bot you create yourself. The README also positions scheduled tasks as making the bot "a lightweight OpenClaw alternative for OpenCode users", which tells you the author sees the scheduling layer, not the chat layer, as the differentiator.

## Architecture: a local client with two outbound connections

The data flow is short enough to hold in your head. Your Telegram message arrives at the bot process, which is running on the same machine as OpenCode. The bot forwards the prompt to the OpenCode API, which defaults to http://localhost:4096. OpenCode does the work. The bot then formats the reply and sends it back through the Telegram Bot API. Both directions are outbound from your machine, which is why the README can claim "No open ports, no exposed APIs". That claim is about the bot, not about OpenCode itself, and the distinction matters if you later expose the OpenCode server. The package depends on @opencode-ai/sdk for the API conversation and grammy for Telegram, with better-sqlite3 storing state locally. The Dockerfile confirms the split: the container runs the bot, and the compose file uses network_mode: host so the container can reach the OpenCode server on the host's loopback interface. The env var OPENCODE_TELEGRAM_CONTAINER=1 is set by compose and, per .env.example, enables warnings for commands that cannot see host files or start and stop OpenCode from inside the container. That is an honest admission that containerising the client degrades some features.

## Installing OpenCode Telegram Bot with npx and connecting it to OpenCode

Two things must exist before the bot is useful: a Telegram bot token and a running OpenCode server. Create the bot by messaging @BotFather and sending /newbot, then copy the token. Get your numeric user ID from @userinfobot. On the machine that runs OpenCode, start the server first.

```bash
opencode serve
```

The README states the bot connects to the local OpenCode API at http://localhost:4096 by default, so leaving that running in a terminal is enough for a first test. Then run the bot through npx, which the README calls the fastest way and which does not require cloning the repository.

```bash
npx @grinev/opencode-telegram-bot@latest
```

The README warns that running this command from the repository root can fail with opencode-telegram: not found, so use it from an ordinary directory. With no configuration present, an interactive wizard starts. According to the README it asks for interface language first, then the bot token, your user ID, the OpenCode API URL, and optional OpenCode server credentials. After the wizard finishes, open your bot in Telegram and send a prompt. If you prefer a persistent install, the README gives a global route instead.

```bash
npm install -g @grinev/opencode-telegram-bot
opencode-telegram start
```

The README describes start as running in the foreground by default and calls that the recommended mode for systemd, Docker and other process managers. A built-in daemon mode exists via opencode-telegram start --daemon, with opencode-telegram status and opencode-telegram stop alongside it, but the README explicitly says to keep using plain start for systemd, pm2 or Docker. Alternatively, .env.example shows the two required variables, TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USER_ID, which you can set in a file instead of answering the wizard.

## The whitelist is the whole security model, and that is a real limitation

The README lists "strict user ID whitelist" as the security feature: no one else can access your bot even if they find it. Read that sentence twice. There is no second factor, no per-command authorisation, and no role separation. Whoever holds the Telegram account whose numeric ID is in TELEGRAM_ALLOWED_USER_ID has full control over an agent that can edit files in your project. Telegram account takeover, a shared device, or a SIM swap becomes a code execution path on your workstation. The README does not document any mitigation for that, and no rate limit or confirmation step for destructive operations is described. The bot does add friction in one place: Custom Commands run from an inline menu with confirmation, and interactive flows accept only relevant input. That is guardrails against accidental taps, not against a compromised account. A second limitation is deployment shape. Running the bot in Docker means it cannot see host files directly, which is why OPENCODE_TELEGRAM_CONTAINER exists to warn you when a command will not work. The file browser, worktree switching and start/stop of OpenCode are the features most likely to degrade there. If you need multi-user access, audit logs, or a hosted control plane, this is the wrong tool; it is deliberately a single-operator bridge.

## How it differs from driving OpenCode in a terminal or a web UI

The obvious alternative is the OpenCode TUI itself, and the difference is not features but attention. A terminal session requires you to be at the machine and looking at it. The bot pushes state to a device you already carry, and the README leans on that with a pinned live status message showing current project or worktree, model, context usage and changed files, plus background notifications when detached sessions reply, ask questions or request permissions. A web UI would need the OpenCode server reachable from the network, which contradicts the localhost-only posture; the bot avoids that by being the outbound party. Compared with generic notification bridges that only forward a ping, this one is bidirectional: you can answer agent questions and approve permissions with inline buttons, switch between Plan and Build modes, pick models from favourites and recent history, and run custom commands including init and review. The trade-off is coupling. Everything you can do is bounded by what the OpenCode API exposes and what the author has wired into the Telegram keyboard, so a new OpenCode capability appears in the bot only after a release. The README also notes that it tracks the main branch, which may include unreleased changes, so the npm release can lag the documentation you are reading.

## Scheduled tasks, voice prompts and what they cost you

Scheduled tasks let you queue a prompt for later or on a recurring interval, which is the feature that turns the bot from a remote control into something closer to a cron job with an agent attached. The README does not document how schedules survive a restart, so verify that yourself before relying on it for anything time-critical. Voice prompts are the other convenience worth naming: you send a voice or audio message, and it is transcribed through a Whisper-compatible API, with optional spoken replies configured in /settings. Both features push the bot beyond pure message relay and into holding credentials for third-party services. The .env.example also documents network escape hatches that suggest real deployment pain: TELEGRAM_PROXY_URL supports socks5, socks4, http and https, TELEGRAM_FORCE_IPV4 exists for environments where IPv6 DNS resolves but outbound IPv6 does not, and TELEGRAM_API_ROOT plus TELEGRAM_PROXY_SECRET let you point the bot at your own reverse proxy when api.telegram.org is blocked. Each of those is a knob you may never touch, or the first thing you configure on a corporate network. The README does not document rollback for a failed upgrade, and there is no migration note for the SQLite state file.

## Licence, maintenance and upgrade cost

The project is MIT licensed, and the package.json confirms it, which means you can fork, modify and redistribute it with the copyright notice and permission text intact. That is unusually permissive for a tool that sits next to your source code, and it removes the licensing question from adoption entirely. What MIT does not give you is a support contract, and the README does not offer one. The last push was on 2026-08-24, the same day as the v0.24.1 release, so the repository is not archived and has been touched recently, but the README's own note that main may contain unreleased changes means the documentation and the npm artefact can disagree. Practically, that shapes your upgrade path: pin a version rather than tracking @latest in anything you depend on, and read the release notes before moving. Because the package version in package.json (0.25.2) is ahead of the most recent listed release (v0.24.1), the repository state and the published release are not the same thing, and you should decide which of the two you are actually running. Note also the engine constraint: Node.js ^22.14.0, ^23.6.0 or >=24, which rules out older runtimes on a long-lived server.

## Conclusion

Adopt it if you already run the OpenCode CLI locally, want to fire off prompts from a phone, and are comfortable with the bot holding a Telegram token and a single-user whitelist. Skip it if you need a hosted service, multi-user access, or a web UI, because the design is one operator, one machine, outbound connections only. Before installing, create the bot with @BotFather, get your numeric ID from @userinfobot, and confirm `opencode serve` answers on http://localhost:4096, since the default OPENCODE_API_URL points there and the bot has nothing to talk to without it.

## FAQ

### How do I install the OpenCode Telegram Bot?

The README gives the fastest route as running npx @grinev/opencode-telegram-bot@latest from a directory that is not the repository root, which starts an interactive setup wizard. A global install is also documented with npm install -g @grinev/opencode-telegram-bot followed by opencode-telegram start.

### Does the OpenCode Telegram Bot need the OpenCode server running?

Yes. OpenCode is listed as a prerequisite, and the README instructs you to run opencode serve on the same machine as the bot. The default API URL is http://localhost:4096, and the bot has nothing to talk to without it.

### Can I run the OpenCode Telegram Bot in Docker?

Yes, the repository ships a Dockerfile and a docker-compose.yml. The compose file uses network_mode: host so the container can reach the OpenCode server on the host, and it sets OPENCODE_TELEGRAM_CONTAINER=1, which the .env.example says enables warnings for commands that cannot see host files or start and stop OpenCode from inside the container.

### Who can access my OpenCode Telegram Bot?

Only the Telegram user ID listed in TELEGRAM_ALLOWED_USER_ID, which the README describes as a strict whitelist so that no one else can access your bot even if they find it. There is no documented second factor or per-command permission layer beyond that ID check.

## Sources

- [Official README](https://github.com/grinev/opencode-telegram-bot#readme)
- [Project repository](https://github.com/grinev/opencode-telegram-bot)
- [Release notes](https://github.com/grinev/opencode-telegram-bot/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/grinev-opencode-telegram-bot