Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 18 or later
  • Git
  • GitHub account and GitHub CLI (gh)
  • Docker and Docker Compose
  • ngrok (for local development without port forwarding)
See the Installation page for detailed setup instructions.

​
Get Started

Get your agent running in two steps:
1

Scaffold a new project

Create a new directory and initialize The Pope Bot:
mkdir my-agent && cd my-agent
npx thepopebot@latest init
This creates a Next.js project with:
  • Configuration files for your agent’s personality and behavior
  • GitHub Actions workflows for job execution
  • Docker configuration
  • Agent templates
You don’t need to create a GitHub repository first — the setup wizard handles that for you.
2

Run the setup wizard

The interactive setup wizard configures everything:
npm run setup
The wizard will:
  1. Check prerequisites - Verifies Node.js, Git, and GitHub CLI are installed
  2. Create GitHub repository - Creates a new repo and pushes your initial commit
  3. Generate GitHub token - Creates a Personal Access Token scoped to your repo
  4. Collect API keys - Prompts for:
    • Anthropic API key (required)
    • OpenAI API key (optional)
    • Brave API key (optional, for web search)
  5. Configure secrets - Sets GitHub repository secrets and variables
  6. Generate .env - Creates your local environment configuration
  7. Build and start - Runs npm run build and starts Docker containers
The wizard asks “Would you like agent jobs to use different LLM settings?” This lets you use different models for chat (fast responses) vs agent jobs (complex tasks).
3

Access your agent

When the wizard finishes, visit your APP_URL to access the web interface.For local development, this is typically:
  • http://localhost (if you have port forwarding)
  • https://your-subdomain.ngrok.io (if using ngrok)
For local installs using ngrok, if your ngrok URL changes (every restart on free plan), you must update APP_URL:
npx thepopebot set-var APP_URL https://your-new-url.ngrok.io
On first visit, you’ll create an admin account with email and password.

​
What Gets Created

After running init and setup, your project contains: 
/
├── .github/workflows/        # GitHub Actions for job execution
├── config/
│   ├── SOUL.md              # Agent personality and identity
│   ├── JOB_PLANNING.md      # System prompt for job planning
│   ├── CRONS.json           # Scheduled jobs
│   └── TRIGGERS.json        # Webhook triggers
├── docker/
│   ├── pi-coding-agent-job/ # Pi agent Docker container
│   └── event-handler/       # Event handler Docker container
├── app/                     # Next.js pages and API routes
├── skills/                  # Agent skills (plugins)
├── .env                     # Local environment variables
└── docker-compose.yml       # Production deployment config

​
Using Your Agent

​
Web Chat

The web interface provides:
  • Real-time chat with your agent
  • Job creation and management
  • File uploads
  • Conversation history
Just type a message and the agent will respond. For complex tasks that require code changes, the agent will create a job.

​
Telegram (Optional)

To connect a Telegram bot: 
npm run setup-telegram
This will:
  1. Prompt for your Telegram bot token
  2. Register the webhook with Telegram
  3. Update your configuration

​
Webhook API

Create jobs programmatically: 
curl -X POST https://your-app-url/api/create-job \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"job": "Update the README with installation instructions"}'
Get your API key from Settings in the web interface.

​
Scheduled Jobs

Edit config/CRONS.json to schedule recurring tasks: 
{
  "jobs": [
    {
      "name": "Daily status check",
      "schedule": "0 9 * * *",
      "type": "agent",
      "job": "Check system status and report any issues",
      "enabled": true
    }
  ]
}
Schedule syntax uses standard cron expressions.

​
Action Types

The Pope Bot supports three action types:
Spins up a Docker container with Pi or Claude Code to execute complex tasks that require reasoning.
  • Uses LLM: Yes
  • Runtime: Minutes to hours
  • Cost: LLM API calls + GitHub Actions minutes
  • Use for: Code changes, analysis, complex workflows
Example:
{
  "type": "agent",
  "job": "Refactor the authentication module to use JWT"
}
Runs a shell command directly on the event handler (your server).
  • Uses LLM: No
  • Runtime: Milliseconds to seconds
  • Cost: Free
  • Use for: Scripts, system commands, quick tasks
Example:
{
  "type": "command",
  "command": "npm test"
}
Makes an HTTP request to an external service.
  • Uses LLM: No
  • Runtime: Milliseconds to seconds
  • Cost: Free
  • Use for: API calls, integrations, notifications
Example:
{
  "type": "webhook",
  "url": "https://api.example.com/notify",
  "method": "POST",
  "vars": {"status": "complete"}
}

​
Customizing Your Agent

​
Personality

Edit config/SOUL.md to define your agent’s personality, expertise, and behavior: 
# Agent Identity

You are a helpful coding assistant specialized in Python and web development.

Your communication style is:
- Concise and technical
- Proactive in suggesting improvements
- Always explain your reasoning

​
Skills

Activate skills by symlinking them into skills/active/: 
ln -s ../browser-tools skills/active/browser-tools
Active skills are automatically loaded and made available to the agent.

​
Next Steps

Installation

Detailed prerequisites and troubleshooting

Configuration

Learn about environment variables and settings

Personality

Customize agent personality and behavior

Deployment

Deploy to a VPS with HTTPS

​
Common Issues

Make sure Docker Desktop is running and you have enough resources allocated.
docker ps  # Check running containers
docker logs event-handler  # Check logs
Verify that:
  1. You’ve pushed to GitHub (git push origin main)
  2. GitHub Actions are enabled in your repository settings
  3. The RUNS_ON variable is set correctly (github-hosted for free tier)
On the free plan, ngrok URLs change on every restart. Either:
  • Upgrade to ngrok paid plan for a static domain
  • Use npx thepopebot set-var APP_URL <new-url> after each restart
  • Deploy to a VPS with a real domain

Build docs developers (and LLMs) love

Get started for freeTalk to us