opencode-dispatch/README.md

Fork of alexanxin/opencode-dispatch — security hardening and Python-only rewrite.

Beyond the Terminal: The Road to a Truly Autonomous AI Agent

opencode-dispatch is a secure Telegram bridge for the opencode CLI. It brings the power of a 120K-star, self-hosted AI agent to your pocket—giving you "Dispatch-style" remote access without the corporate subscription or vendor lock-in.

---

Why opencode-dispatch?

While the industry moves toward closed, subscription-based mobile interfaces, opencode-dispatch stays true to the open-source ethos: Your models, your hardware, your data.

• 📱 Remote Autonomy: Manage codebases, run tests, and refactor files from a Telegram chat.
• 🤖 Model Agnostic: Connect to 75+ providers via Models.dev or run entirely local via Ollama.
• 🔒 Security First: Built-in Telegram Chat ID locking and context isolation.
• ⚡ Lightweight: Runs on a $5 VPS or your local machine with minimal overhead.

The Vision: Building "OpenClaw"

This repository is more than a bridge; it's a foundational layer for a persistent, autonomous agent ecosystem. We are moving beyond stateless terminal commands toward an agent that:

1. Remembers: Persistent cross-session context.
2. Acts: Scheduled task execution and background monitoring.
3. Learns: A plug-and-play skills and personality registry.

---

What You Need

• opencode CLI installed — verify with opencode --version
• A Telegram account
• Python 3.10+
• A Telegram bot token (free from @BotFather)

Quick Setup

Step 1: Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts to get your token.

Step 2: Install Dependencies

pip install -r requirements.txt

Step 3: Configure

cp .env.example .env

Edit .env and set your Telegram bot token and chat ID:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_ALLOWED_CHAT_ID=your_chat_id_here
OPENCODE_API_URL=http://127.0.0.1:5050

Get your chat ID by messaging @userinfobot on Telegram.

Step 4: Start opencode

cd ~/your-project
opencode serve --port 5050

Important: Always cd into a specific project folder first. This limits opencode's access to that folder and its subfolders.

Step 5: Run the Bot

python bot.py

Bot Commands

Command	Description
/start	Welcome message and server info
/status	Server health, session ID, queue size
/working	Check what task is currently being processed
/clear	Clear pending messages from queue

Security

1. Chat ID locking (Required)

The bot requires TELEGRAM_ALLOWED_CHAT_ID to be set and will refuse to start without it. This ensures only your Telegram account can interact with the bot.

2. Limit workspace access

Never run from your home directory (~) or root (/). opencode can access all files in the directory it's started from.

3. Password protect (Recommended)

Set a password to prevent unauthorized local access:

OPENCODE_SERVER_PASSWORD=your-secret opencode serve --port 5050

Then add to .env:

OPENCODE_SERVER_PASSWORD=your-secret

Troubleshooting

"Can't connect to opencode"

• Make sure opencode serve --port 5050 is running in a terminal
• Verify with: curl http://127.0.0.1:5050/global/health

"Bot isn't responding"

• Check your Telegram bot token in .env
• Make sure the bot is running (python bot.py)

"Port already in use"

• Pick a different port: opencode serve --port 5051
• Update OPENCODE_API_URL in .env to match

"opencode command not found"

• Install: curl -fsSL https://opencode.ai/install | bash
• Then run: source ~/.zshrc

Contributing

Found a bug? Have an improvement? Open an issue or submit a pull request!

License

MIT