Build autonomous AI agents that work for you 24/7, individually or in teams.

• Runs 24/7 — set up tasks and your agent handles them around the clock, no babysitting
• Does real work — writes code, opens pull requests, completes multi-step tasks end to end
• Agent clusters — build teams of agents that coordinate and work together on bigger jobs
• Full visibility — every action is a commit you can review, approve, or undo

Get priority support HERE

┌──────────────────────────────────────────────────────────────────────┐
│                                                                      │
│  ┌─────────────────┐         ┌─────────────────┐                     │
│  │  Event Handler  │ ──1──►  │     GitHub      │                     │
│  │ (creates branch)│         │(agent-job/* br) │                     │
│  └────────▲────────┘         └─────────────────┘                     │
│           │                                                          │
│           │  2 (launches Docker container locally)                   │
│           │                                                          │
│           ▼                                                          │
│  ┌─────────────────┐                                                 │
│  │  Docker Agent   │                                                 │
│  │ (coding agent)  │                                                 │
│  └────────┬────────┘                                                 │
│           │                                                          │
│           │  3 (commits, pushes, creates PR)                         │
│           │                                                          │
│           ▼                                                          │
│  ┌─────────────────┐                                                 │
│  │     GitHub      │                                                 │
│  │   (PR opened)   │                                                 │
│  └────────┬────────┘                                                 │
│           │                                                          │
│           │  4a (auto-merge.yml)                                     │
│           │  4b (rebuild-event-handler.yml)                          │
│           │                                                          │
│           5 (notify-pr-complete.yml →                                │
│           │  webhook to event handler)                               │
│           └──────────────────────────►  Event Handler                │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

You interact with your bot via the web chat interface or Telegram (optional). The Event Handler creates an agent-job branch and launches a Docker container locally with the coding agent. The agent does the work, commits the results, pushes, and opens a PR. Auto-merge handles the rest. You get a notification when it's done.

*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 init

This 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 setup

The wizard walks you through everything:

• Checks prerequisites (Node.js, Git, GitHub CLI, Docker)
• Creates a GitHub repository and pushes your initial commit
• Creates a GitHub Personal Access Token (scoped to your repo)
• Configures your public URL and webhook secret
• Syncs settings to .env, database, and GitHub secrets/variables
• 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-telegram to connect a Telegram bot
• Webhook: Send a POST to /api/create-agent-job with your API key to create jobs programmatically
• Cron: Edit agent-job/CRONS.json to 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-token

Paste 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 Coding Agents for details on all five 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 version

Saves your local changes, syncs with GitHub, installs the new version, rebuilds, pushes, and restarts Docker.

What it does:

1. Saves any local changes you've made
2. Pulls the latest from GitHub (stops if there are conflicts)
3. Installs the new version and updates project files
4. Rebuilds your project
5. Pushes everything to GitHub
6. 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.

See CLI Reference for full details on init, managed vs user files, template conventions, and all CLI commands.

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.

thepopebot supports 9 built-in LLM providers (Anthropic, OpenAI, Google, DeepSeek, MiniMax, Mistral, xAI, Kimi, OpenRouter) plus custom OpenAI-compatible endpoints. The chat layer and coding agents are independent — use Claude for interactive chat and a different model for code tasks, or run everything on a single provider.

See Different Models for the full provider reference, admin UI configuration, per-job overrides, and custom provider setup.

SQLite can't create or open its shared-memory (.shm) file. Common causes:

• Antivirus (Windows Defender, etc.) locking the database files — add your project folder to the exclusion list
• Cloud-synced folders (OneDrive, Dropbox, Google Drive) — move your project to a non-synced directory like C:\Projects\