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.
# 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.
# 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.
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
ExperimentalClustering, replication, automatic failover, and split-brain protection across multiple BurrowGate nodes.
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 |
The full README covers everything
Sites, load balancing, TLS, sessions, monitoring, and current limitations - all in one place.