thepopebot: a self-hosted agent stack that wires chat, Docker and GitHub PRs together

What thepopebot actually solves

Most coding agents stop at a diff in a terminal. The work after that (committing, pushing, opening a pull request, telling someone it is finished) is manual, and it is the part that decides whether an agent is useful overnight or only while you are watching. thepopebot's README frames the project as a personal agent, coding environment and communication platform in one app, and the concrete claim underneath that framing is the agent-job path: the agent commits, pushes, opens a PR, and a notify-pr-complete.yml workflow sends a direct message when the merge lands. The intended user is someone who already runs Docker and GitHub, wants the bot on their own hardware and their own tokens, and treats chat as a control surface rather than as the product. The repository is JavaScript, MIT-licensed, and the homepage points at a Skool community called AI Architects, which is where priority support is offered.

Three doors, one event handler

The architecture diagram in the README shows three entry points (browser chat, a live terminal attached to a workspace, and Telegram) all feeding a single component the project calls The Brain, described in the diagram as your event handler. That component picks the coding agent, remembers the session, and runs Docker on your behalf. From there the request splits. Live chat runs the coding agent in-process or in a headless container and streams output to your screen. An agent job instead launches a fresh Docker container, and the README's flow diagram shows it creating an agent-job/<id> branch before the container starts. Two chat modes govern which repository is in play: chatMode agent targets the bot's own repo for configuration and operational talk, while chatMode code targets any repo and branch you select. The design consequence is that the event handler is a single point of configuration for every surface, so a change to provider credentials or the selected coding agent applies to chat, workspaces and background jobs at once.

Live chat and background jobs are not the same product

The README's comparison table draws a line that is easy to miss when skimming the feature list. Live chat is for quick questions and small edits, with the agent running now and streaming to your screen. An agent job is for the instruction pattern the README quotes directly: Build it. DM me when done. That path runs in the background, opens a PR, auto-merges, and DMs you. These have different failure profiles. A live chat that goes wrong costs you a confusing reply. An agent job that goes wrong costs you a merged commit, because auto-merge.yml runs before notify-pr-complete.yml in the documented sequence. The ordering is stated plainly in the flow diagram, and it is the single most consequential design decision in the project. If you want the notification without the merge, the documented flow gives you no obvious place to insert a human, and the README does not describe an approval gate.

Getting it running: the actual commands

The install path is two commands after prerequisites. You scaffold with mkdir my-agent && cd my-agent followed by npx thepopebot@latest init, then run the wizard with npm run setup. According to the README, the wizard checks prerequisites, creates a GitHub repo, generates a PAT, configures your URL, and starts Docker. Prerequisites are Node.js 18 or later, Git, the GitHub CLI, Docker with Docker Compose, and ngrok for local installs without port forwarding; the README notes that VPS and cloud deployments do not need ngrok. After signing in at your APP_URL, three configuration steps are required in order. Providers are added at /admin/event-handler/llms, and everything else pulls credentials from there. The helper LLM (used for one-shot calls such as chat titles, agent-job titles and PR-merge summaries) is chosen at /admin/event-handler/helper-llm, and only providers with keys from the previous step appear. The coding agent is selected at /admin/event-handler/coding-agents. Telegram is optional and lives at /admin/event-handler/telegram. For local installs the README suggests ngrok http 80, and if the ngrok URL changes you run npx thepopebot set-var APP_URL <new-url> and re-register the Telegram webhook from the admin page.

Provider and agent breadth, and what it costs you

The README lists Anthropic, OpenAI, Google, DeepSeek, MiniMax, Mistral, xAI, Kimi, OpenRouter, NVIDIA, or any OpenAI-compatible endpoint as LLM options, and Claude Code, Codex, Gemini, OpenCode, Pi, or Kimi as coding agents. That breadth is real, but it is not free. Each provider needs its own key entered at /admin/event-handler/llms, and the helper LLM is a separate selection drawn only from providers you have already keyed. So a two-provider setup means two keys and a helper choice constrained to those two. The coding agent selection is global: the README says it drives live chat, code workspaces and background agent jobs alike. You cannot, from what is documented, run Claude Code for interactive work and a cheaper agent for background jobs. The README also does not describe what happens when a chosen agent is unavailable, when a provider key is revoked mid-job, or how a partially completed agent job is cleaned up. Those are gaps, not necessarily defects, but they are the questions to ask before pointing this at a repository you care about.

Upgrade mechanics and the protected-file split

Upgrades run through the same CLI: npx thepopebot upgrade for latest stable, npx thepopebot upgrade @beta for beta, or npx thepopebot upgrade 1.2.72 to pin a version. The README states that this installs the new package, syncs managed files, rebuilds, and restarts Docker. The section that follows introduces a distinction between two kinds of files that behave differently, described as being by design, but the supplied material cuts off mid-sentence at that point. I cannot tell you from this material which files are protected and which are overwritten, and that matters a great deal: if your local modifications live in a managed file, an upgrade may replace them. The release cadence visible in the repository is fast, with v1.2.82, v1.2.81 and v1.2.78 all landing within about a week in May 2026. Fast patch releases on a self-hosted stack mean you either track them or you fall behind on fixes, and the upgrade command restarts Docker each time, which interrupts any running agent job. The licence is MIT, which permits commercial use and modification; that is a statement about the licence text, not legal advice, and if you redistribute a modified version you should read the MIT terms yourself, particularly the warranty disclaimer.

Where a general-purpose agent runner is the wrong tool

thepopebot assumes a lot of infrastructure: Node 18, Git, the GitHub CLI, Docker Compose, an internet-reachable endpoint for webhooks, and a GitHub repository the bot can push to. If your work lives on GitLab or in a monorepo where an unattended branch-and-PR cycle creates noise, the core loop does not apply. If you want an assistant inside your editor with no server component, this is a heavier answer than the question. The honest alternative is a plain coding agent CLI run in your own terminal, or a hosted assistant that keeps the repository on someone else's infrastructure. The difference is not features, it is where state lives and who holds the credentials. A terminal agent leaves the diff in front of you and nothing happens until you type the next command. thepopebot moves the decision earlier: you authorize a job, and the merge happens without a second look. If your instinct on reading the auto-merge step was discomfort rather than convenience, that is a signal about fit, not about the software's quality.

Who this fits, and what to check before you install

The fit is narrow and identifiable. You self-host already, you have Docker and the GitHub CLI working, you want agent output to arrive as a pull request with a DM attached, and you accept an internet-reachable endpoint because GitHub webhooks and Telegram both need one. The Telegram integration is described as verified per-user, which is a stronger posture than a shared bot token, but it still means an external service reaches your server. If any of those conditions fails, the setup wizard will surface it early, which is the cheap place to find out. Run npx thepopebot@latest init in a scratch directory and work through npm run setup before you point it at anything real. The step worth scrutinising hardest is the auto-merge workflow, because it is the one part of the documented flow where the project acts without asking.

Editorial conclusion

Adopt thepopebot if you already run Docker and the GitHub CLI, you want the agent's output to arrive as a pull request rather than as text in a chat window, and you are willing to keep an internet-reachable endpoint for webhooks. Do not adopt it if you want a single-purpose coding assistant, if you cannot expose a port to GitHub and Telegram, or if you would rather not hand a background worker auto-merge rights on a repository. Before you commit, verify three things on your own machine: that the coding agent you intend to use is listed at /admin/event-handler/coding-agents, that your ngrok URL survives a restart (otherwise you re-run npx thepopebot set-var APP_URL and re-register the Telegram webhook), and that the auto-merge workflow matches how much you trust unattended commits.

Official sources

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