rudder-agent 0.1.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-agent
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 Anthropic API key (console.anthropic.com)

---

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 Anthropic API key

Rudder uses Claude to understand your messages.

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

---

Step 4 — Install and configure Rudder

Open a terminal in the folder where your AI agent project lives, then run:

pip install rudder-agent
rudder init

The wizard will ask for:

• Your Telegram bot token (from Step 1)
• Your Anthropic API key (from Step 3)
• Your Telegram user ID (from Step 2)
• The path to your working directory — the folder Rudder should have access to

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

This creates a rudder.yaml file in the current folder. Keep this file 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

---

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-agent — installable package
• rudder init setup wizard
• Discord channel
• Custom plugin tools
• pip install rudder-agent[github] — GitHub tools

---

License

MIT