Your personal agent, coding environment, and communication platform — all in one app. Works with any LLM or coding agent. Designed to be simple, unified, secure, and easy.
- 💬 Smart chat integrations — Telegram today; Slack and Discord coming soon. Plus the built-in web chat.
- 🧠 Any LLM — Anthropic, OpenAI, Google, DeepSeek, MiniMax, Mistral, xAI, Kimi, OpenRouter, NVIDIA, or any OpenAI-compatible endpoint.
- 🤖 Any coding agent — Claude Code, Codex, Gemini, OpenCode, Pi, or Kimi.
- 💻 Live coding workspaces — open a terminal in your browser, attach to a running container, share the same session as your chat.
- 🔧 Real work, not just chat — agent writes code, opens a PR, auto-merges, DMs you when it's done.
- 🔐 Yours, fully — runs on your hardware, your repo, your tokens.
Three doors, one brain:
┌── Browser chat ──┐ ┌── Telegram (verified per-user)
│ ▼ ▼
│ ┌──────────────────────────────────┐
│ attach │ The Brain │
│ a live │ (your event handler) │
│ terminal │ │
│ │ • picks the coding agent │
│ │ • picks the coding agent │
│ │ • remembers the session │
│ │ • runs Docker for you │
└── Code ────┤ │
workspace └──────────────┬───────────────────┘
│
┌────────┴────────┐
▼ ▼
┌─────────────┐ ┌─────────────────┐
│ Live chat │ │ Agent job │
│ (right now) │ │ (background) │
│ │ │ │
│ same coding │ │ same coding │
│ agent runs │ │ agent runs in │
│ in-process │ │ a fresh Docker │
│ or in a │ │ container, │
│ headless │ │ opens a PR, │
│ container │ │ DMs you back │
└─────────────┘ └─────────────────┘
| Path | When | What happens |
|---|---|---|
| Live chat | Quick questions, small edits | Coding agent runs now, streams to your screen |
| Agent job | "Build it. DM me when done." | Background worker opens a PR, auto-merges, DMs you |
chatMode |
Repo & branch | Use it for |
|---|---|---|
agent |
Your bot's own repo | Talking to your bot — config, skills, ops |
code |
Any repo + branch you pick | Real coding sessions on a project |
Open a workspace from any code-mode chat and the browser attaches a terminal to a persistent container running your coding agent of choice. Workspace and chat share the same session — fire a question in chat, hop into the terminal, the agent already knows what you were just talking about.
you ──► chat ──► event handler ──► creates `agent-job/<id>` branch
│
▼
launches a Docker container
locally (your chosen agent)
│
▼
agent commits, pushes,
opens a PR
│
▼
auto-merge.yml ──► merged
│
▼
notify-pr-complete.yml ──► DM to you
| Requirement | Install |
|---|---|
| Node.js 18+ | nodejs.org |
| Git | git-scm.com |
| GitHub CLI | cli.github.com |
| Docker + Docker Compose | docker.com |
| ngrok* | ngrok.com (free account + authtoken) |
*ngrok is only needed for local installs without port forwarding. VPS/cloud deployments don't need it.
mkdir my-agent && cd my-agent
npx thepopebot@latest init # scaffold project
npm run setup # interactive wizardThe wizard checks prerequisites, creates a GitHub repo, generates a PAT, configures your URL, and starts Docker. Visit your APP_URL when it finishes.
Local installs: your server needs to be reachable from the internet for GitHub webhooks and Telegram. Use ngrok (
ngrok http 80). If your ngrok URL changes, runnpx thepopebot set-var APP_URL <new-url>and re-register the Telegram webhook from/admin/event-handler/telegram.
npx thepopebot upgrade # latest stable
npx thepopebot upgrade @beta # latest beta
npx thepopebot upgrade 1.2.72 # specific versionInstalls the new package, syncs managed files, rebuilds, restarts Docker.
Two kinds of files behave differently — by design, so an upgrade never blows away your customizations.
┌─ Managed files ──────────────┐ ┌─ Your files ─────────────────┐
│ .github/workflows/ │ │ agent-job/SYSTEM.md │
│ docker-compose.yml │ │ agent-job/CRONS.json │
│ .gitignore │ │ event-handler/TRIGGERS.json │
│ │ │ agents/ │
│ Always replaced with the │ │ skills-library/, skills/ │
│ latest version on every │ │ .env, secrets │
│ init / upgrade. │ │ Never touched by upgrade. │
└──────────────────────────────┘ └──────────────────────────────┘
So you never lose your work — but you might miss a useful template change. Three commands let you pull updates in deliberately:
npx thepopebot audit # show what's drifted from the templates
npx thepopebot diff <file> # show the diff for one file
npx thepopebot reset <file> # replace one file with the latest template
npx thepopebot reset-all # ⚠ nuclear: wipe local edits, restore everythingUse them when release notes mention a SYSTEM.md or workflow improvement you want.
Upgrade failed? See Recovering from a Failed Upgrade.
Two slots, you pick whether they share a model.
- Coding agent — drives everything you actually talk to: live chat in the browser/Telegram, code workspaces, and background agent jobs. One agent, one model. For Claude Code the chat runs in-process via the Claude Agent SDK; for any other agent (Pi, Codex, Gemini, OpenCode, Kimi) it runs in an ephemeral headless container — same chunk shape either way. Configured at
/admin/event-handler/coding-agents. - Helper LLM — small one-shot calls only: chat auto-titles, agent-job titles, PR-merge summaries. Independent provider/model from the coding agent. Configured at
/admin/event-handler/helper-llm.
A coding-agent task can override its model per-run via agent_backend + llm_model on a cron, trigger, or chained agent job.
If you have Claude Pro or Max, you can power Claude Code with your subscription instead of API billing. Generate a token:
npm install -g @anthropic-ai/claude-code
claude setup-tokenPaste it (starts with sk-ant-oat01-) into Admin > Event Handler > Coding Agents > Claude Code (auth mode: OAuth). The same token drives live chat and background agent jobs — no separate API key needed for chat. Add multiple tokens and they rotate LRU on each container launch.
See Coding Agents for details on all six agent backends.
Talk to your bot from your phone. Two steps:
- Wire up the bot — at
/admin/event-handler/telegram, paste the bot token from @BotFather and click Register webhook. - Verify your account — at
/profile/telegram, generate a one-time code and send/verify <code>to your bot. The bot only responds to verified users; unbound chats are silently dropped.
Once verified: /session lists your active threads, /session <id> switches the thread your messages route to. Voice notes are transcribed when an ASSEMBLYAI_API_KEY is set in /admin/event-handler/voice.
See Chat Integrations for the channel adapter pattern and how to add new channels (Slack, Discord coming soon).
thepopebot includes API key authentication, webhook secret validation (fail-closed), session encryption (AES-256-GCM keyed off AUTH_SECRET), per-job API keys with maintenance-cron expiry, and auto-merge path restrictions. 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, your dev server endpoints are publicly accessible with no rate limiting and no TLS on the local hop.
See Security for full details.
SQLite can't create or open its shared-memory (.shm) file. Common causes:
- Antivirus locking the database — add your project folder to the exclusion list
- Cloud-synced folders (OneDrive, Dropbox, Google Drive) — move your project to a non-synced directory
| Document | Description |
|---|---|
| Architecture | Two-layer design, file structure, API endpoints, GitHub Actions, Docker agent |
| CLI Reference | init, managed vs user files, template conventions, all CLI commands |
| Configuration | Admin UI, DB-backed config, infrastructure variables, Docker Compose |
| Customization | Personality, skills, operating system files, using your bot |
| Chat Integrations | Web chat, Telegram, adding new channels |
| Different Models | 10 built-in LLM providers, helper LLM vs coding agent split, per-job overrides, custom providers |
| Auto-Merge | Auto-merge controls, ALLOWED_PATHS configuration |
| Deployment | VPS setup, Docker Compose, HTTPS with Let's Encrypt |
| Coding Agents | 6 coding agent backends, OAuth tokens, LiteLLM proxy, per-agent config |
| How to Build Skills | Guide to building and activating agent skills |
| Pre-Release | Installing beta/alpha builds |
| Code Workspaces | Interactive Docker containers with in-browser terminal |
| Clusters | Agent clusters — groups of Docker containers spawned from role definitions |
| Hacks | Tips, tricks, and workarounds |
| Mobile Testing | Testing on mobile devices |
| Security | Security disclaimer, local development risks |
| Upgrading | Automated upgrades, recovering from failed upgrades |
| Document | Description |
|---|---|
| NPM | Updating skills, versioning, and publishing releases |