thepopebot: a self-hosted AI agent that codes, opens PRs and DMs you

What thepopebot actually is, and who it is built for

thepopebot is not a chat wrapper around one model. It is a self-hosted application that owns a repository, runs coding agents inside Docker, and exposes them through a browser chat, a browser terminal and Telegram. The README describes it as a personal agent, coding environment and communication platform in one app, and the package description is more precise: a two-layer architecture of a Next.js Event Handler plus a Docker Agent.

The intended user is someone who already has a GitHub account, Docker and a machine that can stay reachable. The README states plainly that the bot runs on your hardware, your repo and your tokens. That sentence is the whole pitch and the whole cost. You are not buying a hosted assistant; you are operating one.

The flexibility claim is real in scope. The README lists Anthropic, OpenAI, Google, DeepSeek, MiniMax, Mistral, xAI, Kimi, OpenRouter, NVIDIA, or any OpenAI-compatible endpoint for models, and Claude Code, Codex, Gemini, OpenCode, Pi or Kimi for the coding agent. Those are two independent choices, which matters: the model that writes chat titles is not necessarily the model that edits your code.

Three doors, one brain: the event handler and the Docker agent

The architecture diagram in the README shows three entry points (browser chat, Telegram, and a code workspace) converging on a component it calls The Brain, described as your event handler. That handler picks the coding agent, remembers the session and runs Docker on your behalf. From there the flow splits.

Live chat is the synchronous path. The coding agent runs in-process or in a headless container and streams output to your screen. It suits quick questions and small edits. Agent job is the asynchronous path: the event handler creates an agent-job/<id> branch, launches a Docker container locally with your chosen agent, and the agent commits, pushes and opens a pull request. Then auto-merge.yml merges it and notify-pr-complete.yml sends you a DM.

That chain is the most opinionated thing in the project. A background job does not stop at a proposal; the README's own diagram ends at merged, then a direct message. If you want human review before merge, the workflow files are in .github/ and you would be editing them, not toggling a setting the README documents.

The chatMode distinction is worth internalising early. In agent mode the agent works on the bot's own repository, so you are talking to your bot about its config and skills. In code mode you point it at any repository and branch. Same interface, different blast radius.

Installing thepopebot and getting to a first agent job

The README lists five prerequisites: Node.js 18+, Git, the GitHub CLI, Docker with Docker Compose, and ngrok. The ngrok asterisk is the one people miss. It is only needed for local installs without port forwarding, because GitHub webhooks and Telegram have to reach your server. A VPS or cloud deployment does not need it.

The scaffold is two commands. The first creates a directory and pulls the CLI; the second runs the interactive wizard, which the README says checks prerequisites, creates a GitHub repo, generates a PAT, configures your URL and starts Docker.

mkdir my-agent && cd my-agent
npx thepopebot@latest init

npm run setup

When the wizard finishes, the README says to visit your APP_URL and sign in. Nothing works yet, though. Three settings must be configured in order, and the order is enforced by dependency rather than preference. First, providers at /admin/event-handler/llms, where you add API keys. Second, the helper LLM at /admin/event-handler/helper-llm, where only providers that have keys from step one will appear. Third, the coding agent at /admin/event-handler/coding-agents.

For a local install, the README gives ngrok http 80 as the tunnel command. If the tunnel URL changes, two things follow: run npx thepopebot set-var APP_URL <new-url>, then re-register the Telegram webhook from /admin/event-handler/telegram. Telegram is optional and configured at that same path if you want to talk to the bot from a phone.

Upgrading thepopebot, and the file-sync boundary it depends on

Upgrades go through the CLI, and the README shows three forms: latest stable, the @beta tag, or a pinned version such as 1.2.72. The command installs the new package, syncs managed files, rebuilds and restarts Docker.

npx thepopebot upgrade
npx thepopebot upgrade @beta
npx thepopebot upgrade 1.2.72

The interesting part is the boundary. The README begins a section titled what's protected, what gets updated, explaining that two kinds of files behave differently by design. The text available here cuts off mid-sentence, so the full list of protected paths is not documented in what I can see. That is a genuine gap for anyone planning to customise: before you edit a file, you need to know whether the next upgrade will overwrite it. The repository does ship a CHANGELOG.md and the releases run densely, with v1.2.78, v1.2.81 and v1.2.82 all within a week in May 2026, so upgrades are frequent enough that the question is not theoretical.

The last push to the repository was on 2026-05-13, roughly four months before this writing. The project is not archived, and releases were still landing that day, but the cadence has a visible pause at the end of the record.

Where thepopebot gets in your way

The dependency chain is the first real constraint. A background agent job needs Docker running locally, a GitHub repo the bot can push to, and an agent that can open a pull request. Strip any one of those and the asynchronous path stops being useful. This is not a tool you can evaluate by pointing it at a folder.

Network reachability is the second. The README is explicit that local installs need to be reachable from the internet for GitHub webhooks and Telegram, and that ngrok covers the case without port forwarding. That means a laptop that sleeps will silently stop receiving jobs. The ngrok URL rotation problem is acknowledged in the README with a two-step fix, and it is the kind of maintenance that recurs.

Auto-merge is the third, and the sharpest. The README's job flow ends with auto-merge.yml merging the agent's pull request and notify-pr-complete.yml sending a DM. An agent that commits, pushes and merges without a human gate is the correct design for the stated use case, and the wrong design for a repository with protected branches, required reviews, or compliance obligations. The README does not document a rollback path for a merged agent job.

Finally, Telegram is the only external chat integration shipping today. Slack and Discord are described as coming soon, which is a promise, not a feature. The built-in web chat is the fallback.

thepopebot against a plain CI runner with an agent step

The closest alternative is what most teams already have: a GitHub Actions workflow that installs a coding agent CLI and runs it on an issue or a label. That approach keeps everything inside GitHub. No Docker on your own machine, no ngrok tunnel, no event handler process to keep alive, and the runner is ephemeral by default.

The difference in approach is where the session lives. A CI-based agent is stateless per run. thepopebot keeps a session in its event handler, and the README says a workspace and its chat share that session, so a question typed in chat is known to the agent when you open the terminal. That continuity is the feature a workflow file cannot easily reproduce, and it is also why thepopebot needs a long-running host.

The trade is operational surface. A GitHub Actions agent costs you a YAML file. thepopebot costs you a Node.js server, a Docker daemon, a tunnel, a PAT, and an admin UI with three configuration screens. If your work is batch-shaped and you do not need to talk to the agent mid-task, the workflow file is the smaller commitment. If you want the same agent reachable from your phone at any hour, the event handler is the point.

Editorial conclusion

Adopt thepopebot if you already run Docker and a GitHub account you are willing to hand a personal access token, and you want one agent reachable from browser chat, a terminal and Telegram. Do not adopt it if you want a managed service, if you cannot expose a URL for webhooks, or if you object to an autonomous agent auto-merging into your repository. Verify three things before committing: that your chosen coding agent is among Claude Code, Codex, Gemini, OpenCode, Pi and Kimi; that Docker and Node.js 18+ are present on the host that will run the containers; and that you accept the auto-merge and notify workflows the README describes, because that is where an agent job ends.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. stephengpope/thepopebot on GitHub