Documentation

Install it, configure it, run it

The full reference lives in the GitHub repository and stays versioned with the code. This page is a map to it.

Quick install

A Linux VPS with Docker, public ports 80/443, and a domain pointed at it.

Full quick start
terminal
# fetch the Compose file and start BurrowGate
mkdir burrowgate && cd burrowgate
curl -fsSLO https://raw.githubusercontent.com/Rabbit-Company/BurrowGate/main/docker-compose.yml
docker compose up -d

# read the generated dashboard password
docker compose exec burrowgate cat /app/data/bootstrap-admin-password.txt

# then open
https://SERVER_IP/_burrowgate/admin

Upgrading

The Compose file tracks the latest tag, so pulling always fetches the newest release.

Full upgrade notes
terminal
# pull the new image and recreate the container
docker compose pull
docker compose down
docker compose up -d

Runtime data, certificates, and the encryption key live in ./data and are preserved across upgrades. To upgrade deliberately instead of always tracking latest, pin image: to an exact version such as rabbitcompany/burrowgate:1.9.0 in your docker-compose.yml. See the releases page for what changed before upgrading.

Feature guides

Documentation index

Each guide covers one part of BurrowGate in depth and lives alongside the source code on GitHub.

API Tokens & OpenAPI

Full-access admin automation, live OpenAPI 3.2 JSON, and isolated read-only monitoring credentials.

Bot Management

Identify, verify, analyze, and block bot categories or individual agents per site and route.

Cross-site Authentication

Use one BurrowGate login across a separate frontend and API with signed assertions and backend verification.

Access Lists

Global users, Argon2id passwords, two-factor authentication, and signed identity headers.

Two-Factor Authentication

TOTP and WebAuthn security keys, enrollment flow, per-site key scoping, and reset behavior.

SSO

OIDC single sign-on setup, enforcement, and back-channel logout.

Network Policies

IP, CIDR, ASN, and country rules, default actions, per-route overrides, and precedence order.

Network Privacy

Opt-in Tor exit-node and dynamic ASN category detection (VPN, datacenter, ISP, and more) with monitor and block modes.

Route Policies

Per-path access modes, rate limits, header policies, and caching.

CORS

Per-site/per-route CORS policy that answers preflight requests directly, ahead of verification and access-list sign-in.

HSTS

Site-wide Strict-Transport-Security with optional includeSubDomains and preload.

Body Capture

Optional request/response body capture with size limits, content-type filtering, and expiration.

Header Capture

Optional request/response header capture with default Authorization/Cookie redaction and expiration.

Resend

Replay any captured request from the dashboard, with editable headers/body and redirect following.

Managed Protection

Managed WAF rules, monitor/block modes, and versioned rule metadata.

Adding Challenges

How the challenge provider registry works, for building your own.

Challenge Pages

Customizing the HTML a visitor sees during a browser challenge.

Error Responses

Custom HTML or JSON responses for blocks, limits, and origin failures.

TLS

Let's Encrypt automation via HTTP-01 or DNS-01, uploaded certificates, and key encryption.

Origin mTLS & Certificates

Per-origin client certificates and BurrowGate-issued origin server certificates, usable independently or together.

Static File Origins

Serve a folder directly from disk (no backend process) with clean URLs, SPA fallback, and range support.

Streams

TCP/UDP proxying, incoming and outgoing PROXY protocol, TLS termination, origin health checks, and host networking.

Incoming PROXY Protocol

PROXY protocol v1 and v2 for HTTP, HTTPS, and TCP Streams, with trusted load balancer settings and direct connections.

Scheduled Changes

Defer listener-affecting Site and Stream edits to a chosen time instead of applying them immediately.

Notifications

Origin, connectivity, and IP-ban webhooks to ntfy, Slack, Discord, or signed JSON, with durable ordered delivery.

CrowdSec

Act as a CrowdSec remediation component, enforcing Local API decisions per site, route, and Stream, with optional AppSec (WAF) inspection and captcha decisions served by the challenge chain.

Firewall Sync

Push auto-banned IPs to a UniFi controller, local nftables, OVH's edge firewall, or an AWS VPC Network ACL, with a never-ban whitelist and oldest-first eviction.

Bandwidth

Client vs. upstream bandwidth counters and aggregation.

System Monitoring

Live status and historical graphs for host/container CPU, memory, disk, and network usage, plus alert thresholds - all on the dashboard's Host page.

GeoIP & ASN

MaxMind country and ASN database setup and the optional auto-updater profile.

OpenMetrics

Prometheus and OpenTelemetry Collector export reference.

Update Notifications

How the dashboard checks GitHub Releases and shows an update badge with release notes.

High Availability

Experimental

Clustering, replication, automatic failover, and split-brain protection across multiple BurrowGate nodes.

Configuration

Common environment variables

The most frequently changed settings. See .env.example on GitHub for the complete list.

Variable Default Description
BG_HOST 0.0.0.0 Listener address
BG_HTTP_PORT / BG_HTTPS_PORT 80 / 443 Internal listener ports
BG_HTTP_PROXY_PROTOCOL / BG_HTTPS_PROXY_PROTOCOL false Accept incoming PROXY v1/v2 from trusted load balancers on the HTTP or HTTPS listener
BG_PROXY_PROTOCOL_TRUSTED_CIDRS empty Load balancer connection IPs or CIDRs, separated by commas or whitespace. Required when listener PROXY support is enabled
BG_PROXY_PROTOCOL_ALLOW_DIRECT true Allow direct connections on enabled incoming PROXY listeners, including TCP Streams
DATABASE_URL sqlite://./data/burrowgate.db Bun.SQL database URL - also accepts postgres:// and mysql://
BG_ADMIN_USERNAME admin Dashboard username
BG_ADMIN_PASSWORD generated Dashboard password
BG_MASTER_KEY generated Encrypts certificate and ACME private keys - back this up with your database
BG_EVENT_RETENTION_DAYS 7 Default monitoring retention for new sites and streams
BG_GEOIP_ENABLED true Enable country-level GeoIP enrichment
BG_GEOIP_ASN_ENABLED same as BG_GEOIP_ENABLED Enable ASN enrichment
BG_OPENMETRICS_ENABLED false Expose /_burrowgate/metrics for Prometheus-compatible scraping
BG_UPDATE_CHECK_ENABLED true Check GitHub Releases hourly and show a dashboard update badge
BG_DEFAULT_POW_DIFFICULTY 18 Default SHA-256 challenge difficulty
BG_WEBSOCKET_ENABLED true Enable WebSocket proxying
BG_ACME_EMAIL empty Default ACME contact email for Let's Encrypt
Need more detail

The full README covers everything

Sites, load balancing, TLS, sessions, monitoring, and current limitations - all in one place.