rudder-ai 0.2.0

Mobile control panel for AI agents — control your bots from Telegram

Rudder

Mobile control panel for AI agents. Control your bots from Telegram — from anywhere, on any device.

"Rudder puts every developer in the captain's chair of their AI agents."

---

What is Rudder?

You build AI agents. They run on your machine. But when you're away from your desk, you're flying blind.

Rudder wraps your agent with a Telegram interface so you can:

• Ask questions in plain English ("what positions are open?")
• Approve or deny tool calls before they execute
• Run commands on your machine remotely
• Check logs and file contents from your phone

---

Quick Start

pip install rudder-ai
rudder init      # guided setup wizard
rudder start     # launch your bot

Then open Telegram and message your bot.

---

What Rudder Can Do

Command	Example
Read files	"show me the last 20 lines of app.log"
Run commands	"run my_script" → Approve/Deny on phone
List files	"what files are in my project?"
Answer questions	"what's the status of my agent?"

---

Requirements

• Python 3.10+
• A Telegram account and bot token (free)
• An API key for your chosen AI model

---

Supported Models

Rudder works with any of these AI providers — pick one during rudder init:

Provider	Models	Install
Claude / Anthropic (recommended)	claude-sonnet-4-6, claude-opus-4-6	pip install rudder-ai[anthropic]
OpenAI	gpt-4o, gpt-4-turbo, gpt-3.5-turbo	pip install rudder-ai[openai]
Grok / xAI	grok-3-beta, grok-2	pip install rudder-ai[openai]
Ollama (local, free)	llama3, mistral, phi3, gemma, any	pip install rudder-ai
Custom	Any OpenAI-compatible API	pip install rudder-ai[openai]

Custom option supports Groq, Together.ai, Mistral, Azure OpenAI, and any provider with an OpenAI-compatible endpoint.

---

Setup — Step by Step

Step 1 — Create a Telegram bot

1. Open Telegram and search for @BotFather (official blue checkmark)
2. Send this message: /newbot
3. BotFather will ask: "What's the name of your bot?"
   • This is the display name shown in chats — e.g. My Agent Bot
4. BotFather will ask: "What username would you like to give it?"
   • Must end in bot — e.g. myagent_bot or MyAgentBot
   • Must be unique across all of Telegram
5. BotFather will reply with your bot token — it looks like:

   1234567890:AAFabcdefGHIjklmNOPqrstUVwxyz123456
   

6. Copy and save this token — you'll need it in Step 4

---

Step 2 — Get your Telegram user ID

Rudder only accepts messages from you — it needs your personal user ID to enforce this.

1. Open Telegram and search for @userinfobot
2. Send any message (e.g. /start)
3. It will reply with your Id number — e.g. 123456789
4. Copy this number

---

Step 3 — Get an API key for your chosen model

Claude (recommended)

1. Go to console.anthropic.com
2. Sign up or log in → API Keys → Create Key
3. Copy the key — starts with sk-ant-...

OpenAI

1. Go to platform.openai.com
2. Sign up or log in → API Keys → Create new secret key
3. Copy the key — starts with sk-...

Grok / xAI

1. Go to console.x.ai
2. Sign up or log in → API Keys → Create API Key
3. Copy the key

Ollama (local — no API key needed)

1. Install Ollama from ollama.com
2. Run: ollama pull llama3 (or any model you want)
3. No API key required

---

Step 4 — Install and configure Rudder

Open a terminal in your project folder, then run:

# For Claude (recommended):
pip install rudder-ai[anthropic]

# For OpenAI or Grok:
pip install rudder-ai[openai]

# For Ollama (local):
pip install rudder-ai

Then run the setup wizard:

rudder init

The wizard will ask for:

• Your Telegram bot token (from Step 1)
• Your Telegram user ID (from Step 2)
• Your working directory — the folder Rudder should have access to
• Your AI model provider and API key (from Step 3)

Tip: Run rudder init from inside your project folder. When asked for the working directory, press Enter to use the current folder.

This creates a rudder.yaml file. Keep it safe — it contains your API keys.

---

Step 5 — Start Rudder

rudder start

You should see:

Rudder started. Open Telegram and message your bot.

---

Step 6 — Message your bot

Open Telegram, search for your bot by its username (e.g. @myagent_bot), and send a message.

Try:

• hello
• what files are in my project?
• show me the contents of app.log

---

Configuration Reference

Your rudder.yaml file supports these options:

# Required
telegram_token: "your-telegram-bot-token"
allowed_user_id: 123456789
working_dir: "/path/to/your/project"

# Model provider (choose one block below)

# --- Claude / Anthropic ---
model_provider: "anthropic"
model: "claude-sonnet-4-6"
anthropic_api_key: "sk-ant-..."

# --- OpenAI ---
# model_provider: "openai"
# model: "gpt-4o"
# openai_api_key: "sk-..."

# --- Grok / xAI ---
# model_provider: "ollama"
# model: "grok-3-beta"
# openai_api_key: "your-xai-key"
# ollama_base_url: "https://api.x.ai/v1"

# --- Ollama (local) ---
# model_provider: "ollama"
# model: "llama3"
# ollama_base_url: "http://localhost:11434/v1"

# --- Custom OpenAI-compatible API (Groq, Together, Mistral, etc.) ---
# model_provider: "ollama"
# model: "your-model-name"
# openai_api_key: "your-api-key"
# ollama_base_url: "https://your-provider/v1"

---

Troubleshooting

Bot doesn't respond

• Make sure rudder start is running in your terminal
• Check that your bot token in rudder.yaml is correct
• Try sending /start to your bot first

"Unauthorized" error

• Your allowed_user_id in rudder.yaml doesn't match your actual Telegram ID
• Re-check your ID with @userinfobot

"Working directory not found" error

• The working_dir path in rudder.yaml doesn't exist on your machine
• Update it to a valid folder path

Bot stops when I close the terminal

• This is expected — the bot runs in your terminal session
• For always-on usage, set it up as a background service

---

Security

• Only your Telegram user ID can send commands
• Destructive actions (bash, file writes) require explicit Approve/Deny on your phone
• Your API keys stay on your machine — never sent anywhere else
• Self-hosted: you control everything

---

Roadmap

• Telegram channel
• Bash, read/write file, list files tools
• Approve/Deny on mobile
• pip install rudder-ai — installable package
• rudder init setup wizard
• Multi-model support — Claude, OpenAI, Grok, Ollama, any OpenAI-compatible API
• Discord channel
• Custom plugin tools
• pip install rudder-ai[github] — GitHub tools

---

License

MIT