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.
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 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 (rebuild-event-handler.yml) │
│ │ │ │
│ 5 (notify-pr-complete.yml / │ │
│ │ notify-job-failed.yml) │ │
│ └───────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
You interact with your bot via the web chat interface or Telegram (optional). 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 notification when it's done.
| Requirement | Install |
|---|---|
| Node.js 18+ | nodejs.org |
| npm | Included with Node.js |
| Git | git-scm.com |
| GitHub CLI | cli.github.com |
| Docker + Docker Compose | docker.com (installer requires admin password) |
| ngrok* | ngrok.com (free account + authtoken required) |
*ngrok is only required for local installs without port forwarding. VPS/cloud deployments don't need it. Sign up for a free ngrok account, then run ngrok config add-authtoken <YOUR_TOKEN> before starting setup.
Step 1 — Scaffold a new project:
mkdir my-agent && cd my-agent
npx thepopebot@latest initThis creates a Next.js project with configuration files, GitHub Actions workflows, and agent templates. You don't need to create a GitHub repo first — the setup wizard handles that.
Step 2 — Run the setup wizard:
npm run setupThe wizard walks you through everything:
- Checks prerequisites (Node.js, Git, GitHub CLI)
- Creates a GitHub repository and pushes your initial commit
- Creates a GitHub Personal Access Token (scoped to your repo)
- Collects API keys (Anthropic required; OpenAI, Brave optional)
- Sets GitHub repository secrets and variables
- Generates
.env - Builds the project and starts Docker for you
That's it. Visit your APP_URL when the wizard finishes.
- Web Chat: Visit your APP_URL to chat with your agent, create jobs, upload files
- Telegram (optional): Run
npm run setup-telegramto connect a Telegram bot - Webhook: Send a POST to
/api/create-jobwith your API key to create jobs programmatically - Cron: Edit
config/CRONS.jsonto schedule recurring jobs
Your bot has two sides — a chat side and an agent side.
Chat is the conversational part. When you talk to your bot in the web UI or Telegram, it uses the chat LLM. This runs on your server and responds in real time.
Agent is the worker. When your bot needs to write code, modify files, or do a bigger task, it spins up a separate job that runs in a Docker container on GitHub. That job uses the agent LLM.
By default, both use the same model. But during setup, you can choose different models for each — for example, a faster model for chat and a more capable one for agent jobs. The wizard asks "Would you like agent jobs to use different LLM settings?" and lets you pick.
If you have a Claude Pro ($20/mo) or Max ($100+/mo) subscription, you can use it to power your agent jobs instead of paying per API call. During setup, choose Anthropic as your agent provider and say yes when asked about a subscription.
You'll need to generate a token:
# Install Claude Code CLI (if you don't have it)
npm install -g @anthropic-ai/claude-code
# Generate your token (opens browser to log in)
claude setup-tokenPaste the token (starts with sk-ant-oat01-) into the setup wizard. Your agent jobs will now run through your subscription. Note that usage counts toward your Claude.ai limits, and you still need an API key for the chat side.
See Claude Code vs Pi for more details on the two agent backends.
Local installs: Your server needs to be reachable from the internet for GitHub webhooks and Telegram. On a VPS/cloud server, your APP_URL is just your domain. For local development, use ngrok (
ngrok http 80) or port forwarding to expose your machine.If your ngrok URL changes (it changes every time you restart ngrok on the free plan), you must update APP_URL everywhere:
# Update .env and GitHub variable in one command: npx thepopebot set-var APP_URL https://your-new-url.ngrok.io # If Telegram is configured, re-register the webhook: npm run setup-telegram
npx thepopebot upgrade # latest stable
npx thepopebot upgrade @beta # latest beta
npx thepopebot upgrade 1.2.72 # specific versionSaves your local changes, syncs with GitHub, installs the new version, rebuilds, pushes, and restarts Docker.
What it does:
- Saves any local changes you've made
- Pulls the latest from GitHub (stops if there are conflicts)
- Installs the new version and updates project files
- Rebuilds your project
- Pushes everything to GitHub
- Restarts Docker containers (if running)
Pushing to main triggers the rebuild-event-handler.yml workflow on your server. It detects the version change, runs thepopebot init, updates THEPOPEBOT_VERSION in the server's .env, pulls the new Docker image, restarts the container, rebuilds .next, and reloads PM2 — no manual docker compose needed.
Upgrade failed? See Recovering from a Failed Upgrade.
When you ran thepopebot init the first time, it scaffolded a project folder with two kinds of files:
Your files — These are yours to customize. init will never overwrite them:
| Files | What they do |
|---|---|
config/SOUL.md, JOB_PLANNING.md, JOB_AGENT.md, etc. |
Your agent's personality, behavior, and prompts |
config/CRONS.json, TRIGGERS.json |
Your scheduled jobs and webhook triggers |
app/ |
Next.js pages and UI components |
docker/pi-coding-agent-job/ |
The Dockerfile for the Pi coding agent job container |
Managed files — These are infrastructure files that need to stay in sync with the package version. init auto-updates them for you:
| Files | What they do |
|---|---|
.github/workflows/ |
GitHub Actions that run jobs, auto-merge PRs, rebuild on deploy |
docker-compose.yml |
Defines how your containers run together (Traefik, event handler, runner) |
docker/event-handler/ |
The Dockerfile for the event handler container |
.dockerignore |
Keeps unnecessary files out of Docker builds |
CLAUDE.md |
AI assistant context for your project |
- Managed files are updated automatically to match the new package version
- Your files are left alone — but if the package ships new defaults (e.g., a new field in
CRONS.json),initlets you know:
Updated templates available:
These files differ from the current package templates.
config/CRONS.json
To view differences: npx thepopebot diff <file>
To reset to default: npx thepopebot reset <file>
You can review at your own pace:
npx thepopebot diff config/CRONS.json # see what changed
npx thepopebot reset config/CRONS.json # accept the new templateIf you've made custom changes to managed files (e.g., added extra steps to a GitHub Actions workflow), use --no-managed so init doesn't overwrite your changes:
npx thepopebot init --no-managedThe templates/ directory contains files scaffolded into user projects by thepopebot init. Two naming conventions handle files that npm or AI tools would otherwise misinterpret:
.template suffix — Files ending in .template are scaffolded with the suffix stripped. This is used for files that npm mangles (.gitignore) or that AI tools would pick up as real project docs (CLAUDE.md).
In templates/ |
Scaffolded as |
|---|---|
.gitignore.template |
.gitignore |
CLAUDE.md.template |
CLAUDE.md |
api/CLAUDE.md.template |
api/CLAUDE.md |
CLAUDE.md exclusion — The scaffolding walker skips any file named CLAUDE.md (without the .template suffix). This is a safety net so a bare CLAUDE.md accidentally added to templates/ never gets copied into user projects where AI tools would confuse it with real project instructions.
All commands are run via npx thepopebot <command> (or the npm run shortcuts where noted).
Project setup:
| Command | Description |
|---|---|
init |
Scaffold a new project, or update templates in an existing one |
setup |
Run the full interactive setup wizard (npm run setup) |
setup-telegram |
Reconfigure the Telegram webhook (npm run setup-telegram) |
reset-auth |
Regenerate AUTH_SECRET, invalidating all sessions |
Templates:
| Command | Description |
|---|---|
diff [file] |
List files that differ from package templates, or diff a specific file |
reset [file] |
List all template files, or restore a specific one to package default |
Secrets & variables:
These commands set individual GitHub repository secrets/variables using the gh CLI. They read GH_OWNER and GH_REPO from your .env. If VALUE is omitted, you'll be prompted with masked input (keeps secrets out of shell history).
| Command | Description |
|---|---|
set-agent-secret KEY [VALUE] |
Set AGENT_<KEY> GitHub secret and update .env |
set-agent-llm-secret KEY [VALUE] |
Set AGENT_LLM_<KEY> GitHub secret |
set-var KEY [VALUE] |
Set a GitHub repository variable |
GitHub secrets use a prefix convention so the workflow can route them correctly:
AGENT_— Protected secrets passed to the Docker container (filtered from LLM). Example:AGENT_GH_TOKEN,AGENT_ANTHROPIC_API_KEYAGENT_LLM_— LLM-accessible secrets (not filtered). Example:AGENT_LLM_BRAVE_API_KEY- No prefix — Workflow-only secrets, never passed to container. Example:
GH_WEBHOOK_SECRET
thepopebot includes API key authentication, webhook secret validation (fail-closed), session encryption, secret filtering in the Docker agent, and auto-merge path restrictions. However, all software carries risk — thepopebot is provided as-is, and you are responsible for securing your own infrastructure. If you're running locally with a tunnel (ngrok, Cloudflare Tunnel, port forwarding), be aware that your dev server endpoints are publicly accessible with no rate limiting and no TLS on the local hop.
See Security for full details on what's exposed, the risks, and recommendations.
The Event Handler (chat, Telegram, webhooks) and Jobs (Docker agent) are two independent layers — each can run a different LLM. Use Claude for interactive chat and a cheaper or local model for long-running jobs, mix providers per cron entry, or run everything on a single model.
See Running Different Models for the full guide: Event Handler config, job defaults, per-job overrides, provider table, and custom provider setup.
| 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 |
| Chat Integrations | Web chat, Telegram, adding new channels |
| Running Different Models | Event Handler vs job model config, per-job overrides, providers, custom provider |
| Auto-Merge | Auto-merge controls, ALLOWED_PATHS configuration |
| Deployment | VPS setup, Docker Compose, HTTPS with Let's Encrypt |
| Claude Code vs Pi | Comparing the two agent backends (subscription vs API credits) |
| How to Build Skills | Guide to building and activating agent skills |
| Pre-Release | Installing beta/alpha builds |
| Security | Security disclaimer, local development risks |
| Upgrading | Automated upgrades, recovering from failed upgrades |
| Document | Description |
|---|---|
| NPM | Updating skills, versioning, and publishing releases |
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}