| name | telegram-agent |
| description | Deploy a Telegram bot agent on mshkn disposable computers with lampas as the async LLM proxy. Use when someone wants to set up an AI agent that receives messages via Telegram, thinks via Claude, and executes tool calls on ephemeral VMs. |
| allowed-tools | Bash, Read, Write, Glob, Grep |
telegram-agent
A Telegram bot agent running entirely on mshkn disposable computers. No computer is ever "always on" — they boot, process one input, checkpoint, and die. The agent receives user messages via Telegram, thinks via Claude API (through lampas), and executes tool calls on ephemeral VMs.
Architecture: Two Boxes
Box A — The Brain
Runs brain.py. Handles all ingress (Telegram messages, LLM responses, tool results). On each boot:
- Read input from exec payload (Telegram message, Claude response, or tool result)
- Append to conversation history on disk (
/agent/state.json)
- Either call Claude via lampas or dispatch tool commands to Box B
- Checkpoint and die
Box B — The Hands
Executes tool commands from Claude (npm install, write files, build, deploy). Each tool batch runs on a fresh fork of the previous Box B checkpoint, preserving installed packages and files across batches.
Flow
User sends Telegram message
→ Telegram webhook → mshkn ingress → fork Box A from "agent-brain" checkpoint
→ Box A reads message, calls Claude via lampas
→ Box A checkpoints, dies
Claude responds (via lampas callback)
→ mshkn ingress → fork Box A from latest "agent-brain" checkpoint
→ Box A parses JSON actions, sends Telegram messages, dispatches tools to Box B
→ Box A checkpoints, dies
Tool completes on Box B
→ Box B callbacks result to mshkn ingress → fork Box A
→ Box A reads result, calls Claude with it
→ Cycle repeats until Claude sends final Telegram message
Prerequisites
- mshkn API access: Account + API key on a mshkn server
- lampas: Deployed at lampas.dev (or your own instance). Used as async proxy for Claude API calls.
- Telegram Bot Token: Create a bot via @BotFather
- Anthropic API Key: For Claude API calls via lampas
- mshkn ingress rules: Two rules — one for Telegram webhook, one for lampas callbacks
Files
Quick Start
See SETUP.md for the full provisioning guide. The high-level steps:
- Create two ingress rules (Telegram webhook + Claude callback)
- Create recipes for Box A (python3+curl) and Box B (nodejs+npm+jq+file+curl)
- Create Box A, upload brain.py + config.json, checkpoint as "agent-brain"
- Configure Starlark transforms on ingress rules
- Set Telegram webhook URL
- Send a message to your bot
