Skip to main content

​
Prerequisites

The Pope Bot requires several tools to be installed on your system before you begin.

​
Required Tools

The Pope Bot requires Node.js 18 or later.Install:
  • Download from nodejs.org
  • npm is included with Node.js
Verify:
node --version  # Should be 18.0.0 or higher
npm --version
Git is required for repository management and version control.Install:Verify:
git --version
The GitHub CLI (gh) is used for authentication and repository operations.Install:Setup:
gh auth login
Follow the prompts to authenticate with your GitHub account.Verify:
gh auth status
Docker is required to run the agent containers and production deployment.Install:
  • Download Docker Desktop from docker.com
  • Docker Compose is included with Docker Desktop
  • Installation requires admin/sudo password
Verify:
docker --version
docker compose version
Make sure Docker Desktop is running before proceeding with setup.
ngrok is only required for local installations without port forwarding. VPS/cloud deployments don’t need it.Why ngrok? Your server needs to be reachable from the internet for GitHub webhooks and Telegram integration.Install:
  1. Sign up for a free account at ngrok.com
  2. Download from ngrok.com/download
  3. Configure your authtoken:
ngrok config add-authtoken <YOUR_TOKEN>
Start ngrok:
ngrok http 80
On the free plan, your ngrok URL changes every time you restart. Consider upgrading to a paid plan for a static domain, or deploy to a VPS.
Alternatives to ngrok:
  • Port forwarding on your router
  • Cloudflare Tunnel
  • Deploy to a VPS (recommended for production)

​
API Keys

You’ll need at least one LLM provider API key:

​
Optional Services

  • Brave Search API - For web search capabilities (optional)

​
System Requirements

​
Minimum Requirements

  • CPU: 2 cores
  • RAM: 4GB
  • Disk: 10GB free space
  • Network: Stable internet connection
  • CPU: 4+ cores
  • RAM: 8GB+
  • Disk: 20GB+ SSD
  • Network: High-speed internet

​
Platform Support

Fully supported on macOS 10.15 (Catalina) and later.Notes:
  • Docker Desktop for Mac required
  • Apple Silicon (M1/M2) fully supported

​
Installation Steps

1

Verify prerequisites

Before starting, verify all required tools are installed:
node --version    # 18.0.0 or higher
npm --version
git --version
gh auth status    # Must be authenticated
docker --version
docker compose version
For local development:
ngrok version
ngrok config check
2

Start ngrok (local development only)

If developing locally without port forwarding, start ngrok in a separate terminal:
ngrok http 80
Keep this running and note your ngrok URL (e.g., https://abc123.ngrok.io). You’ll need this for the APP_URL during setup.
Skip this step if deploying to a VPS or using port forwarding.
3

Scaffold the project

Create a new directory and initialize The Pope Bot:
mkdir my-agent && cd my-agent
npx thepopebot@latest init
This scaffolds:
  • Next.js project structure
  • GitHub Actions workflows
  • Docker configuration
  • Agent templates and config files
4

Run the setup wizard

Start the interactive setup:
npm run setup
The wizard will guide you through:1. Prerequisites Check
  • Validates Node.js, Git, GitHub CLI
2. GitHub Repository
  • Creates a new repository
  • Pushes initial commit
3. GitHub Token
  • Creates a Personal Access Token
  • Scoped to your repository
4. App URL
  • For local: https://your-ngrok-url.ngrok.io
  • For VPS: https://yourdomain.com
5. LLM Provider (Chat)
  • Choose provider (Anthropic/OpenAI/Google/Custom)
  • Enter API key
  • Choose model
6. Agent LLM Settings (Optional)
  • Option to use different settings for agent jobs
  • Can use different model or provider
7. OAuth Token (Optional)
  • If using Claude subscription
  • Paste token from claude setup-token
8. Web Search (Optional)
  • Enter Brave API key for web search
  • Only available for Anthropic and OpenAI providers
9. GitHub Secrets & Variables
  • Automatically sets repository secrets
  • Configures variables
10. Build & Start
  • Generates .env
  • Runs npm install
  • Runs npm run build
  • Starts Docker containers
5

Access your agent

Once setup completes, visit your APP_URL in a browser.First Visit:
  1. You’ll be prompted to create an admin account
  2. Enter email and password
  3. This becomes your login for the web interface
Web Interface Features:
  • Chat with your agent
  • Create and manage jobs
  • Upload files
  • View conversation history
  • Access settings (API keys, crons, triggers)

​
Post-Installation

​
Verify Installation

Check that all services are running: 
docker ps
You should see:
  • event-handler - Next.js server
  • traefik - Reverse proxy
  • runner - GitHub Actions runner (if using self-hosted)

​
Test Your Agent

  1. Visit your APP_URL
  2. Log in with your admin account
  3. Send a test message in the chat
  4. Try creating a simple job:
Create a file called test.txt with the content "Hello from The Pope Bot!"
The agent should create a job, execute it, and open a PR.

​
Configure Telegram (Optional)

To add Telegram integration:
1

Create a Telegram bot

  1. Message @BotFather on Telegram
  2. Send /newbot
  3. Follow prompts to create your bot
  4. Save the bot token
2

Run setup-telegram

npm run setup-telegram
Enter your bot token when prompted.
3

Test the bot

  1. Find your bot on Telegram
  2. Send /start
  3. Chat with your agent

​
Troubleshooting

Make sure you’ve authenticated with GitHub CLI:
gh auth login
gh auth status
If still failing, try:
gh auth refresh
Check Docker is running:
docker info
Check logs:
docker logs event-handler
docker logs traefik
Restart Docker:
  • Docker Desktop: Restart from system tray
  • Linux: sudo systemctl restart docker
Check resources:
  • Docker Desktop: Increase RAM/CPU in settings
  • Minimum 4GB RAM recommended
Another service is using port 80.Find what’s using port 80:
# macOS/Linux
sudo lsof -i :80

# Stop the service or change ports in docker-compose.yml
Alternative: Modify docker-compose.yml to use different ports:
ports:
  - "8080:80"  # Use port 8080 instead
Then update ngrok:
ngrok http 8080
Check Actions are enabled:
  1. Go to your repository on GitHub
  2. Settings → Actions → General
  3. Enable “Allow all actions and reusable workflows”
Check workflows exist:
ls .github/workflows/
Should contain:
  • run-job.yml
  • auto-merge.yml
  • notify-pr-complete.yml
  • notify-job-failed.yml
  • rebuild-event-handler.yml
Check you’ve pushed:
git push origin main
Free plan limitation: ngrok free plan generates a new URL on every restart.Update APP_URL after restart:
# Get new ngrok URL from ngrok dashboard
npx thepopebot set-var APP_URL https://new-url.ngrok.io

# If Telegram is configured:
npm run setup-telegram
Solutions:
  1. Upgrade ngrok - Paid plans include static domains
  2. Deploy to VPS - Use a real domain (recommended)
  3. Port forwarding - Configure your router
Clean install:
rm -rf node_modules package-lock.json
npm install
npm run build
Check Node.js version:
node --version  # Must be 18+
Update dependencies:
npm update
Verify API key: Check your .env file for correct API key.Check account status:Ensure you have:
  • Valid API key
  • Sufficient credits/quota
  • Correct model access
Update API key:
# For chat (event handler)
# Edit .env directly

# For agent jobs
npx thepopebot set-agent-secret ANTHROPIC_API_KEY

​
Updating

Keep The Pope Bot up to date: 
npx thepopebot upgrade          # Latest stable
npx thepopebot upgrade @beta    # Latest beta
npx thepopebot upgrade 1.2.72   # Specific version
The upgrade command:
  1. Saves local changes
  2. Pulls latest from GitHub
  3. Installs new version
  4. Rebuilds project
  5. Pushes to GitHub
  6. Restarts Docker containers

​
Next Steps

Quickstart

Learn how to use your agent

Configuration

Configure environment variables and settings

Personality

Customize agent personality and behavior

Deployment

Deploy to production with HTTPS

Build docs developers (and LLMs) love

Get started for freeTalk to us