thepopebot
Autonomous AI agents. All the power. None of the leaked API keys.
Why thepopebot?
Secure by default — Other frameworks hand credentials to the LLM and hope for the best. thepopebot is different: the AI literally cannot access your secrets, even if it tries. Secrets are filtered at the process level before the agent's shell even starts.
The repository IS the agent — Every action your agent takes is a git commit. You can see exactly what it did, when, and why. If it screws up, revert it. Want to clone your agent? Fork the repo — code, personality, scheduled jobs, full history, all of it goes with your fork.
Free compute, built in — Every GitHub account comes with free cloud computing time. thepopebot uses that to run your agent. One task or a hundred in parallel — the compute is already included.
Self-evolving — The agent modifies its own code through pull requests. Every change is auditable, every change is reversible. You stay in control.
How It Works
┌───────────────────────────────────────────────────────────────────────┐
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Event Handler │ ──1──► │ GitHub │ │
│ │ (creates job) │ │ (job/* branch) │ │
│ └────────▲────────┘ └────────┬────────┘ │
│ │ │ │
│ │ 2 (triggers run-job.yml) │
│ │ │ │
│ │ ▼ │
│ │ ┌─────────────────┐ │
│ │ │ Docker Agent │ │
│ │ │ (runs Pi, PRs) │ │
│ │ └────────┬────────┘ │
│ │ │ │
│ │ 3 (creates PR) │
│ │ │ │
│ │ ▼ │
│ │ ┌─────────────────┐ │
│ │ │ GitHub │ │
│ │ │ (PR opened) │ │
│ │ └────────┬────────┘ │
│ │ │ │
│ │ 4a (auto-merge.yml) │
│ │ 4b (update-event-handler.yml) │
│ │ │ │
│ 5 (Telegram notification) │ │
│ └───────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────┘
You talk to your bot on Telegram (or hit a webhook). The Event Handler creates a job branch. GitHub Actions spins up a Docker container with the Pi coding agent. The agent does the work, commits the results, and opens a PR. Auto-merge handles the rest. You get a Telegram notification when it's done.
Get FREE server time on Github!
| thepopebot | Other platforms | |
|---|---|---|
| Public repos | Free. $0. GitHub Actions doesn't charge. | $20-100+/month |
| Private repos | 2,000 free minutes/month (every GitHub plan, including free) | $20-100+/month |
| Infrastructure | GitHub Actions (already included) | Dedicated servers |
You just bring your own Anthropic API key.
Get Started
Prerequisites
| Requirement | Install |
|---|---|
| Node.js 18+ | nodejs.org |
| npm | Included with Node.js |
| Git | git-scm.com |
| GitHub CLI | cli.github.com |
| ngrok* | ngrok.com |
*ngrok is only required for local development. Production deployments don't need it.
Three steps
Step 1 — Fork this repository:
GitHub Actions are disabled by default on forks. Go to the Actions tab in your fork and enable them.
Step 2 — Clone your fork:
git clone https://github.com/YOUR_USERNAME/thepopebot.git
cd thepopebot
Step 3 — Run the setup wizard:
npm run setup
The wizard handles everything:
- Checks prerequisites (Node.js, Git, GitHub CLI, ngrok)
- Creates a GitHub Personal Access Token
- Collects API keys (Anthropic required; OpenAI, Groq, and Brave Search optional)
- Sets GitHub repository secrets and variables
- Sets up Telegram bot
- Starts the server + ngrok, generates
event_handler/.env - Registers webhooks and verifies everything works
After setup, message your Telegram bot to create jobs!
Docs
| Document | Description |
|---|---|
| Architecture | Two-layer design, file structure, API endpoints, GitHub Actions, Docker agent |
| Configuration | Environment variables, GitHub secrets, repo variables, ngrok, Telegram setup |
| Customization | Personality, skills, operating system files, using your bot, security details |
| Auto-Merge | Auto-merge controls, ALLOWED_PATHS configuration |
| How to Use Pi | Guide to the Pi coding agent |
| Security | Security hardening plan |