Self-Hosting Pounce

System Requirements

Component	Minimum	Recommended
Docker	24+	Docker Engine or Docker Desktop current stable
Docker Compose	v2	v2 current stable
PostgreSQL	14+	16+
RAM	2 GB	4 GB
Disk	10 GB	20 GB+
CPU	1 core	2+ cores

Supported OS: Ubuntu 22.04+, Debian 12+, macOS 14+. Manual Node installs are intended for developers only.

Install Options

Option 1: Release Bundle (recommended)

The easiest way to run Pounce is the release bundle from the Pounce site. It includes Docker Compose files, an environment template, and release notes.

# Download and start the latest release
curl -fsSL https://pouncefirst.com/install.sh | bash

The installer creates ~/pounce, copies .env.example to .env, pulls Docker images, and starts the stack.

Before production use, edit ~/pounce/.env:

cd ~/pounce
nano .env
docker compose up -d

Pounce starts on port 3000. Visit http://localhost:3000 to begin setup.

The release bundle includes:

• Pounce app (Node.js standalone)
• PostgreSQL database
• Automatic health checks
• .env.example with placeholders only
• Release notes and update instructions

Option 2: Direct Download

If you want to inspect files first:

curl -fsSLO https://github.com/fabermade/pounce/releases/latest/download/pounce-selfhost.tar.gz
tar -xzf pounce-selfhost.tar.gz
cd pounce-selfhost
cp .env.example .env
nano .env
docker compose pull
docker compose up -d

Option 3: Manual Developer Install

Manual source installs are for development and internal debugging. Customers should use the release bundle.

git clone https://github.com/fabermade/pounce.git
cd pounce
npm install
cp .env.example .env
npm run db:migrate
npm run build
npm run preview

Environment Variables

Required environment variables:

Variable	Description	Example
DATABASE_URL	PostgreSQL connection string	postgresql://...
SESSION_SECRET	Random 32+ char string for session signing	openssl rand -hex 32
PIPELINE_TOKEN	Random 32+ char string for internal background jobs	openssl rand -hex 32
APP_URL	Public URL of this Pounce instance	https://pounce.yourdomain.com
POUNCE_LICENSE_KEY	License key from your Pounce account	PC-XXXX-XXXX-XXXX

See Environment Variables for the complete reference.

Production Deployment

Systemd Service

Create /etc/systemd/system/pounce.service:

[Unit]
Description=Pounce Lead Response
After=network.target postgresql.service

[Service]
Type=simple
User=pounce
WorkingDirectory=/opt/pounce
ExecStart=/usr/bin/node /opt/pounce/dist/server.js
Restart=on-failure
RestartSec=10
Environment=NODE_ENV=production

# Security
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/opt/pounce/logs

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable pounce
sudo systemctl start pounce

Nginx Reverse Proxy

server {
    listen 80;
    server_name pounce.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name pounce.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/pounce.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/pounce.yourdomain.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    # Webhook endpoints need larger body size
    location /api/stripe/webhook {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        client_max_body_size 10M;
    }

    location /api/webhook/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        client_max_body_size 10M;
    }
}

SSL with Let’s Encrypt

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d pounce.yourdomain.com
sudo certbot renew --dry-run  # Verify auto-renewal

First-Run Setup

1. Enter your license key (PC-XXXX-XXXX-XXXX)
2. Create your admin account (email + password)
3. Configure your first lead form (name, fields, redirect URL)
4. Set up email sending (Resend API key + domain verification)
5. Optionally connect a booking provider (Cal.com or Calendly)

Backup Strategy

Daily Database Backup

pg_dump pounce | gzip > /backups/pounce-$(date +%Y%m%d).sql.gz

Add to crontab:

0 2 * * * pg_dump pounce | gzip > /backups/pounce-$(date +\%Y\%m\%d).sql.gz

What to Back Up

Item	Location	Frequency
PostgreSQL database	pg_dump	Daily
Environment variables	.env file	On change
License key	Admin dashboard	On initial setup
Nginx config	/etc/nginx/sites-available/	On change

Restoring from Backup

gunzip < /backups/pounce-20260427.sql.gz | psql pounce
cp .env.backup .env
sudo systemctl restart pounce

Updating Pounce

Manual Install

cd /opt/pounce
curl -fsSLO https://github.com/fabermade/pounce/releases/latest/download/pounce-selfhost.tar.gz
tar -xzf pounce-selfhost.tar.gz --strip-components=1
docker compose pull
docker compose up -d

Docker

cd ~/pounce
docker compose pull
docker compose up -d

Some updates may require database migrations:

# Manual install
npm run db:migrate

# Docker — migrations run automatically on startup

Always read the changelog before updating.

Customizing Base Rules

Pounce’s AI behavior is governed by base rules in src/config/base-rules.md. This file is loaded at runtime (not bundled), so you can edit it without rebuilding.

Common customizations:

• Add industry-specific rules (e.g., HIPAA compliance for healthcare)
• Adjust response length targets
• Add disallowed topics specific to your business
• Modify intent filtering criteria

After editing, restart Pounce:

# systemd
sudo systemctl restart pounce

# Docker
docker compose restart

See AI Responses for details on how base rules fit into the prompt assembly.

Security Checklist

• Change default admin password after first login
• Set a strong SESSION_SECRET (32+ random characters)
• Enable HTTPS (Let’s Encrypt or your own certificate)
• Set NODE_ENV=production
• Restrict database access to localhost only
• Configure firewall: only allow ports 22, 80, 443
• Set up automatic security updates: sudo apt install unattended-upgrades
• Store .env with chmod 600 permissions
• Never commit .env to version control (it’s in .gitignore)
• Regularly update Node.js and npm dependencies