Why Remote Control?

Sometimes you need AI assistance but don't have your development machine:

Scenarios:

• On your phone during a meeting — need to check a deployment
• At a conference — want to show a demo without opening a laptop
• On call at 2am — need to diagnose and fix an incident from your phone
• Pair programming — your colleague triggers actions on your agent

The concept: Your AI agent runs on a server or your dev machine. You send commands from any device via a messaging app, and the agent executes them.

Architecture Overview

The remote control pattern:

┌──────────┐     ┌──────────────┐     ┌──────────────┐
│ Telegram │────▶│  Bridge Bot  │────▶│  AI Agent    │
│ (phone)  │◀────│  (server)    │◀────│  (dev machine│
│          │     │              │     │   or server) │
└──────────┘     └──────────────┘     └──────────────┘

Components:

1. Messaging app (Telegram, Slack, Discord) — your remote control
2. Bridge bot — receives messages, forwards to agent, returns results
3. AI agent (OpenCode, Claude Code) — executes commands on your codebase

Why Telegram? Free, fast, excellent bot API, works on every platform, supports markdown formatting in responses.

The Telegram Bot Bridge

How remote-opencode-telegram works:

Setup:

# 1. Create a Telegram bot via @BotFather
# 2. Get your bot token

# 3. Install the bridge
npm install -g remote-opencode-telegram

# 4. Configure
export TELEGRAM_BOT_TOKEN="your-bot-token"
export TELEGRAM_ALLOWED_USERS="your-telegram-user-id"
export OPENCODE_PROJECT_DIR="/path/to/your/project"

# 5. Start
remote-opencode-telegram

Usage from your phone:

You: /status
Bot: "Project: model-prism | Branch: main | Clean working tree"

You: "What's the current test coverage?"
Bot: "Running tests... Coverage: 84.2% (target: 80%)"

You: "Fix the failing test in auth.test.js"
Bot: "Reading auth.test.js... Found issue: mock not reset
      between tests. Applied fix. Tests now passing."

Security Considerations

Remote agent control is powerful — and dangerous without safeguards:

Authentication:

• Only allow specific Telegram user IDs (whitelist)
• Never expose the bot to public channels
• Use a unique bot token, rotate regularly

Authorization:

• Define allowed actions (read, write, deploy)
• Block destructive commands by default
• Require confirmation for risky operations

You: "Delete the database migration files"
Bot: "⚠ DESTRUCTIVE ACTION: This will delete 12 migration files.
      Type 'CONFIRM DELETE' to proceed."

Network security:

• Run the bridge on your local network or VPN
• Don't expose agent ports to the internet
• Use SSH tunnels for remote access to dev machines

Audit logging:

• Log every command and response
• Include timestamp, user, and action
• Review logs regularly for unexpected activity

Practical Use Cases

What remote control is actually useful for:

Incident Response:

Alert: "API latency spike detected"
You (from phone): "Check the last 50 error logs for the API service"
Bot: "Found 47 connection timeout errors to the payment provider.
      Started at 14:32. Payment provider status page shows outage."
You: "Enable the circuit breaker for payment processing"
Bot: "Circuit breaker enabled. Payment requests will return
      cached responses. Applied to production."

Quick Checks:

You: "What PRs are open?"
Bot: "3 open PRs: #142 (auth refactor), #145 (pagination),
      #147 (fix typo in README)"

You: "How many requests did we process today?"
Bot: "42,350 requests. 99.2% success rate. Top model:
      claude-sonnet-4 (68%). Total cost: $127.40"

Demo Mode:

You (at a conference): "Start the demo server and share the URL"
Bot: "Demo server running at https://demo.your-app.com
      Sample data loaded. Ready for presentation."

Beyond Telegram

Other remote control interfaces:

Slack integration:

• Use Slack's bot API instead of Telegram
• Better for team-wide agent access
• Channels per project, threads per task

Voice control:

• "Hey Siri, tell my agent to run the tests"
• Requires additional voice-to-text bridge
• Useful for truly hands-free operation

Webhook triggers:

• GitHub webhook → agent runs on PR
• Monitoring alert → agent investigates
• Calendar event → agent prepares meeting notes

API endpoint:

# Simple HTTP API for your agent
curl -X POST https://your-agent.com/api/command \
  -H "Authorization: Bearer your-token" \
  -d '{"command": "Run tests and report coverage"}'

Setting Up Your Remote Control

A step-by-step guide:

Step 1: Create the Telegram bot

• Open Telegram, search for @BotFather
• Send /newbot, follow prompts
• Save the bot token

Step 2: Find your Telegram user ID

• Search for @userinfobot in Telegram
• Send it any message to get your user ID
• Add this to the allowed users list

Step 3: Choose your deployment

• Local: Run on your dev machine (requires it to be on)
• Server: Run on a VPS alongside your project
• Cloud: Run as a cloud function triggered by Telegram webhooks

Step 4: Configure safety rules

• Whitelist allowed user IDs
• Define read-only vs. read-write permissions
• Set up confirmation for destructive actions
• Enable audit logging

Step 5: Test thoroughly

• Start with read-only commands
• Verify authentication works correctly
• Test the confirmation flow for dangerous actions
• Ensure no information leaks in error messages

---quiz question: What is the main purpose of remote agent control? options:

• { text: "To make AI agents run faster", correct: false }
• { text: "To send commands to your AI agent from any device — phone, chat app, or other systems — without needing a terminal", correct: true }
• { text: "To share your agent with the public", correct: false } feedback: Remote control lets you interact with your AI coding agent from anywhere — handling incidents from your phone at 2am, checking deployments during meetings, or running demos from a conference, all without opening a laptop.

---quiz question: What is the most critical security measure for remote agent control? options:

• { text: "Using the latest version of the AI model", correct: false }
• { text: "Whitelisting specific user IDs and requiring confirmation for destructive actions", correct: true }
• { text: "Running the bot on a fast server", correct: false } feedback: Authentication (whitelist user IDs) and authorization (confirmation for destructive actions) are the minimum security requirements. Without them, anyone who discovers your bot could execute commands on your codebase.

---quiz question: What is the typical architecture for remote agent control? options:

• { text: "Phone directly connects to the AI model", correct: false }
• { text: "Messaging app → Bridge bot → AI agent running on your dev machine or server", correct: true }
• { text: "AI agent sends push notifications to your phone", correct: false } feedback: The standard pattern is: messaging app (Telegram/Slack) sends commands to a bridge bot, which forwards them to your AI agent running on your development machine or server. Results flow back through the same path.