Skip to main content

​
Overview

The Pope Bot uses environment variables for core configuration. These are set in .env in your project root and control the Event Handler’s behavior (web chat, Telegram, webhooks, and job summaries).
Never commit the actual .env file with real secrets! Use .env.example as a template.

​
Quick Start

Copy the example file and fill in your values: 
cp templates/.env.example .env
# Edit .env with your values
Generate required secrets: 
# Auth secret for session encryption
openssl rand -base64 32

# Telegram webhook secret
openssl rand -hex 32

​
Required Variables

These variables must be set for the system to function: | Variable | Description | Example | |----------|-------------|---------|| | AUTH_SECRET | Secret for NextAuth session encryption (auto-generated by setup) | openssl rand -base64 32 | | APP_URL | Public URL for webhooks, Telegram, and Traefik hostname | https://mybot.example.com | | APP_HOSTNAME | Hostname extracted from APP_URL (used by docker-compose/Traefik) | mybot.example.com | | GH_TOKEN | GitHub Personal Access Token (needs repo, workflow scopes) | ghp_your_token_here | | GH_OWNER | GitHub repository owner username | your_github_username | | GH_REPO | GitHub repository name | your_repo_name |

​
LLM Provider Configuration

Configure which LLM provider powers your Event Handler (chat, Telegram, webhooks): | Variable | Description | Default | |----------|-------------|---------|| | LLM_PROVIDER | LLM provider: anthropic, openai, google, or custom | anthropic | | LLM_MODEL | Model name override (provider-specific default if unset) | Provider default | | LLM_MAX_TOKENS | Max tokens for responses | 4096 | | ANTHROPIC_API_KEY | API key for Anthropic provider | sk-ant-your_key_here | | OPENAI_API_KEY | API key for OpenAI provider or Whisper voice transcription | Required for OpenAI | | GOOGLE_API_KEY | API key for Google provider | Required for Google | | CUSTOM_API_KEY | API key for custom OpenAI-compatible endpoints | Optional | | OPENAI_BASE_URL | Custom OpenAI-compatible base URL (for custom provider) | http://localhost:11434/v1 |
The Event Handler and Job agent models are configured independently. Jobs use GitHub repository variables. See LLM Models for details.

​
Telegram Configuration

Optional variables for Telegram integration: | Variable | Description | How to Get | |----------|-------------|------------|| | TELEGRAM_BOT_TOKEN | Bot token from @BotFather | Message @BotFather on Telegram | | TELEGRAM_CHAT_ID | Default chat ID for notifications (restricts bot to this chat) | Use @userinfobot or check webhook logs | | TELEGRAM_WEBHOOK_SECRET | Secret for validating Telegram webhooks | openssl rand -hex 32 | | TELEGRAM_VERIFICATION | Verification code for getting your chat ID | verify-abc12345 |

​
Voice Transcription

Optional API keys for voice input:
VariableDescription
OPENAI_API_KEYRequired for Whisper voice transcription
ASSEMBLYAI_API_KEYRequired for real-time voice input (alternative to Whisper)

​
Webhook Security

VariableDescription
GH_WEBHOOK_SECRETSecret for GitHub Actions webhook auth (must match GitHub secret)
This secret must be set as both an environment variable AND a GitHub secret. Use npx thepopebot set-agent-secret GH_WEBHOOK_SECRET <value>.

​
Docker Deployment

Variables specific to docker-compose deployment: | Variable | Description | Default | |----------|-------------|---------|| | AUTH_TRUST_HOST | Trust host header behind reverse proxy (Traefik, ngrok, etc.) | true | | LETSENCRYPT_EMAIL | Email for Let’s Encrypt automatic SSL certificates | Optional (self-signed if unset) | | THEPOPEBOT_VERSION | Package version for Docker image tags (auto-set by postinstall) | Auto-set | | EVENT_HANDLER_IMAGE_URL | Custom event handler Docker image | stephengpope/thepopebot:event-handler-* | | JOB_IMAGE_URL | Custom job agent Docker image | stephengpope/thepopebot:pi-coding-agent-job-* |

​
Advanced Configuration

| Variable | Description | Default | |----------|-------------|---------|| | DATABASE_PATH | Override SQLite database location | data/thepopebot.sqlite |

​
GitHub Secrets vs Environment Variables

The Pope Bot uses two separate configuration systems:

​
Environment Variables (.env)

Control the Event Handler (your server):
  • Web chat interface
  • Telegram responses
  • Webhook processing
  • Job completion summaries
Set these in your .env file. Restart your server after changes: 
docker compose up -d  # Docker deployment
# or
npm run dev          # Local development

​
GitHub Secrets

Control the Job Agent (Docker containers on GitHub Actions):
  • Agent credentials (filtered from LLM’s bash output)
  • LLM-accessible credentials (for skills, browser logins)
  • GitHub Actions workflow authentication
Set these via CLI: 
# Protected secrets (filtered from LLM)
npx thepopebot set-agent-secret AGENT_NAME value

# LLM-accessible secrets (for skills)
npx thepopebot set-agent-llm-secret KEY_NAME value
| Prefix | Purpose | Example | |--------|---------|---------|| | AGENT_ | Protected credentials (filtered from LLM’s bash) | AGENT_GH_TOKEN, AGENT_ANTHROPIC_API_KEY | | AGENT_LLM_ | LLM-accessible credentials (skills, browser logins) | AGENT_LLM_BRAVE_API_KEY |
Required GitHub secrets:
  • GH_WEBHOOK_SECRET - Random secret for webhook authentication (must match .env)

​
GitHub Repository Variables

Configure in Settings → Secrets and variables → Actions → Variables: | Variable | Description | Default | |----------|-------------|---------|| | APP_URL | Public URL for the event handler | Required | | AUTO_MERGE | Set to false to disable auto-merge of job PRs | Enabled | | ALLOWED_PATHS | Comma-separated path prefixes for auto-merge | /logs | | JOB_IMAGE_URL | Docker image path for job agent | stephengpope/thepopebot:pi-coding-agent-job-${THEPOPEBOT_VERSION} | | EVENT_HANDLER_IMAGE_URL | Docker image path for event handler | stephengpope/thepopebot:event-handler-${THEPOPEBOT_VERSION} | | RUNS_ON | GitHub Actions runner label | ubuntu-latest | | LLM_PROVIDER | LLM provider for jobs | anthropic | | LLM_MODEL | LLM model name for the agent | Provider default | Set these via CLI: 
npx thepopebot set-var VARIABLE_NAME value
Job model configuration is independent from Event Handler configuration. You can use different models for chat vs jobs.

​
Changing APP_URL

If your public URL changes (e.g., after restarting ngrok or changing domains):
  1. Update APP_URL and APP_HOSTNAME in .env
  2. Update the APP_URL GitHub repository variable: 
    npx thepopebot set-var APP_URL https://new-url.example.com
  3. Restart Docker: 
    docker compose up -d
  4. Re-register Telegram webhook (if configured): 
    npm run setup-telegram

​
Example Configuration

​
Local Development

# .env
AUTH_SECRET=your_generated_secret
AUTH_TRUST_HOST=true
APP_URL=http://localhost:3000
APP_HOSTNAME=localhost

GH_TOKEN=ghp_your_token
GH_OWNER=your_username
GH_REPO=your_repo

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

​
Production Docker

# .env
AUTH_SECRET=your_generated_secret
AUTH_TRUST_HOST=true
APP_URL=https://bot.example.com
APP_HOSTNAME=bot.example.com

GH_TOKEN=ghp_your_token
GH_OWNER=your_username
GH_REPO=your_repo

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_CHAT_ID=123456789
TELEGRAM_WEBHOOK_SECRET=your_webhook_secret

GH_WEBHOOK_SECRET=your_webhook_secret

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

LETSENCRYPT_EMAIL=your@email.com

​
Using Local Models (Ollama)

# .env - Event Handler uses Claude
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

# GitHub Variables - Jobs use local Ollama
npx thepopebot set-var LLM_PROVIDER custom
npx thepopebot set-var LLM_MODEL qwen3:8b
npx thepopebot set-var OPENAI_BASE_URL http://host.docker.internal:11434/v1
npx thepopebot set-var RUNS_ON self-hosted

Build docs developers (and LLMs) love

Get started for freeTalk to us