Self-hosted personal AI agent that writes, runs, schedules, and persists workflows from natural language descriptions via Telegram or API.
OpenTulpa is a self-hosted personal AI agent framework that transforms natural language workflow descriptions into executable code. Built on LangGraph and FastAPI, it supports interaction via Telegram DM or internal API.
Core Capabilities#
Memory & Personalization#
- Persistent memory layer via mem0, retaining user preferences, files, and conversation history across sessions
- Multimodal input support: text, files, images, voice
- Automatic context compression and history summarization to control token consumption
Code Generation & Execution#
- Natural language workflow description → Agent writes script → Sandbox execution → Scheduling → Persistence
- Skills system: reusable workflows stored as SKILL.md (user/global scope)
- APScheduler for timed tasks, periodic jobs, and long-running processes
Security & Approval Mechanism#
- Externally impactful operations require explicit user approval (pending → approved/denied/expired → executed)
- Approvals can be scoped to single-use, expiration time, or operation scope
- Telegram webhook verified via
x-telegram-bot-api-secret-token
Extension Capabilities#
- crawl4ai integration for web scraping
- Optional Browser Use Cloud for browser automation (form filling, web operations)
- Multi-LLM support via OpenRouter routing
Typical Use Cases#
| Scenario | Example |
|---|---|
| Email Management | Daily Gmail summary, extract action items |
| Market Monitoring | Stock/crypto price tracking, Alpaca integration |
| Team Collaboration | Slack bots, scheduled standup reminders |
| Content Subscriptions | Giphy trending subscriptions, RSS/Feed aggregation |
| Automated Response | GitHub webhook monitoring for CI failures |
Technical Architecture#
- Runtime Framework: LangGraph (agent graph orchestration) + LangChain (tool chains)
- Web Framework: FastAPI
- Memory Layer: mem0
- Persistence: SQLite (multiple DB files)
- Scheduler: APScheduler
- LLM Routing: OpenRouter (required)
Quick Start#
# Clone repository
git clone https://github.com/kvyb/opentulpa.git
cd opentulpa
# Configure environment
cp .env.example .env
# Edit .env, add OPENROUTER_API_KEY
# Start in API mode
uv run python -m opentulpa
Interface Options#
- Telegram Bot: Interact via DM with webhook security verification
- Internal API:
POST /internal/chatfor direct calls
Runtime Data#
.opentulpa/— Memory, config, contexttulpa_stuff/— Generated scripts and artifacts.opentulpa/logs/agent_behavior.jsonl— Structured behavior logs
Cost Estimation#
- ~$0.011 per intelligent loop
- Most tasks complete in 3-4 loops
- ~$3.30-$4.40 for 100 messages