Skip to main content
Anubis supports three configuration methods that work together:
  1. Command-line flags - Direct invocation arguments
  2. Environment variables - Uppercase flag names with underscores
  3. Policy files - YAML-based configuration for bot rules and advanced features

​
Configuration Priority

Settings are applied in this order (highest to lowest priority):
  1. Command-line flags
  2. Environment variables
  3. Default values
Environment variable names are uppercase versions of flag names with hyphens replaced by underscores. For example, --cookie-domain becomes COOKIE_DOMAIN.

​
Core Configuration Flags

​
Network and Binding

​
--bind

Environment: BIND
Default: :8923 Network address for Anubis to listen on. 
# Listen on all interfaces, port 8923
--bind=":8923"

# Listen on localhost only
--bind="127.0.0.1:8923"

# Listen on specific IP
--bind="192.168.1.10:8923"

# Unix domain socket
--bind="/run/anubis/anubis.sock"

​
--bind-network

Environment: BIND_NETWORK
Default: tcp Network family to bind to. Accepts any value supported by Go’s net.Listen. 
--bind-network=tcp    # TCP/IP sockets
--bind-network=unix   # Unix domain sockets

​
--target

Environment: TARGET
Default: http://localhost:3923 URL of the service Anubis should protect and proxy to. 
# HTTP backend
--target=http://localhost:3000

# HTTPS backend
--target=https://backend.internal:8443

# Unix socket backend
--target=unix:///var/run/app.sock

​
Challenge Configuration

​
--difficulty

Environment: DIFFICULTY
Default: 4 The number of leading zeroes required in proof-of-work challenge responses. Higher values increase difficulty and client computation time. 
--difficulty=4    # Default, suitable for most use cases
--difficulty=5    # Harder, for high-threat environments
--difficulty=3    # Easier, for low-power clients

​
Metrics and Health Checks

​
--metrics-bind

Environment: METRICS_BIND
Default: :9090 Network address for the Prometheus metrics and health check server. 
--metrics-bind=":9090"
--metrics-bind="127.0.0.1:9090"  # Localhost only
The metrics server exposes two endpoints:
  • GET /metrics - Prometheus metrics
  • GET /healthz - Health check (returns OK when serving)
curl http://localhost:9090/healthz

​
--metrics-bind-network

Environment: METRICS_BIND_NETWORK
Default: tcp Network family for the metrics server. Environment: COOKIE_DOMAIN
Default: unset The domain for which Anubis cookies are valid. Set this to your root domain. 
# Allow cookies for all subdomains of example.com
--cookie-domain=example.com
Do not include a port number in COOKIE_DOMAIN. Unlike REDIRECT_DOMAINS, the cookie domain must be a bare domain name.
Environment: COOKIE_DYNAMIC_DOMAIN
Default: false Automatically set cookie domain based on the request hostname. 
--cookie-dynamic-domain=true
You cannot set both COOKIE_DOMAIN and COOKIE_DYNAMIC_DOMAIN at the same time.
Environment: COOKIE_EXPIRATION_TIME
Default: 168h (7 days) How long challenge pass cookies remain valid. 
--cookie-expiration-time=168h    # 7 days
--cookie-expiration-time=24h     # 1 day
--cookie-expiration-time=720h    # 30 days
Environment: COOKIE_PREFIX
Default: anubis-cookie Prefix for browser cookies created by Anubis. Useful for avoiding conflicts. 
--cookie-prefix=myapp-anubis
This creates cookies named:
  • myapp-anubis-auth
  • myapp-anubis-cookie-verification
Environment: COOKIE_SECURE
Default: true Enable the Secure flag on cookies, requiring HTTPS. 
--cookie-secure=true   # Require HTTPS (recommended)
--cookie-secure=false  # Allow HTTP (development only)
If using plain HTTP, you must set --cookie-secure=false or cookies will be rejected by browsers.
Environment: COOKIE_SAME_SITE
Default: None Sets the SameSite attribute for cookies. Valid values: None, Lax, Strict, Default. 
--cookie-same-site=None      # Cross-site usage (requires Secure)
--cookie-same-site=Lax       # Some cross-site, recommended for HTTP
--cookie-same-site=Strict    # Same-site only
If COOKIE_SECURE=false, None is automatically downgraded to Lax. Environment: COOKIE_PARTITIONED
Default: false Enable the partitioned (CHIPS) flag for iframe isolation. 
--cookie-partitioned=true

​
Policy Files

​
--policy-fname

Environment: POLICY_FNAME
Default: Built-in policy Path to the YAML policy file defining bot rules, thresholds, and Open Graph settings. 
--policy-fname=/etc/anubis/botPolicies.yaml
For details on policy file syntax, see Bot Policies.

​
Logging

​
--slog-level

Environment: SLOG_LEVEL
Default: INFO Log level for structured logging. Valid values: DEBUG, INFO, WARN, ERROR. 
--slog-level=DEBUG  # Verbose logging, shows all requests
--slog-level=INFO   # Standard logging
--slog-level=WARN   # Warnings and errors only
--slog-level=ERROR  # Errors only
Set to DEBUG to see detailed request evaluation information.

​
Signing Keys

Signing keys are required when using persistent storage backends or running multiple Anubis instances behind the same load balancer.

​
--ed25519-private-key-hex

Environment: ED25519_PRIVATE_KEY_HEX
Default: Random (generated at startup) Hex-encoded 64-character ED25519 private key for signing JWTs. 
--ed25519-private-key-hex=a1b2c3d4e5f6...  # 64 hex characters
Generate a key: 
openssl rand -hex 32

​
--ed25519-private-key-hex-file

Environment: ED25519_PRIVATE_KEY_HEX_FILE
Default: unset Path to a file containing the hex-encoded ED25519 private key. 
--ed25519-private-key-hex-file=/etc/anubis/signing.key
Only one of --ed25519-private-key-hex or --ed25519-private-key-hex-file may be set.

​
--hs512-secret

Environment: HS512_SECRET
Default: unset Secret for JWT HS512 algorithm. If set, ED25519 will not be used. 
--hs512-secret="your-very-long-secret-string"
Cannot be used with ED25519 options.

​
IP Address Detection

​
--use-remote-address

Environment: USE_REMOTE_ADDRESS
Default: false Read the client’s IP from the network socket instead of headers. 
--use-remote-address=true
Only use this for development or when Anubis directly terminates traffic. In production with a reverse proxy, use X-Real-IP or X-Forwarded-For headers instead.

​
--custom-real-ip-header

Environment: CUSTOM_REAL_IP_HEADER
Default: unset Read the client’s real IP from a custom header name. 
--custom-real-ip-header=CF-Connecting-IP  # Cloudflare
--custom-real-ip-header=X-Forwarded-For

​
--xff-strip-private

Environment: XFF_STRIP_PRIVATE
Default: true Strip private addresses from X-Forwarded-For headers. 
--xff-strip-private=true   # Remove private IPs
--xff-strip-private=false  # Keep all IPs

​
JWT Configuration

​
--jwt-restriction-header

Environment: JWT_RESTRICTION_HEADER
Default: X-Real-IP Restrict JWT validity to match a specific header value (typically client IP). 
--jwt-restriction-header=X-Real-IP
The JWT is only valid if the current value of this header matches the value when the JWT was created.

​
--difficulty-in-jwt

Environment: DIFFICULTY_IN_JWT
Default: false Include the difficulty level in JWT claims for debugging and statistics. 
--difficulty-in-jwt=true

​
Path Configuration

​
--base-prefix

Environment: BASE_PREFIX
Default: unset Global path prefix for all Anubis endpoints. 
--base-prefix=/myapp
With this set:
  • Challenge page: /myapp/ instead of /
  • API endpoints: /myapp/.within.website/x/anubis/...
BASE_PREFIX must start with a slash and must not end with a slash.

​
--strip-base-prefix

Environment: STRIP_BASE_PREFIX
Default: false Remove the base prefix when forwarding requests to the target. 
--base-prefix=/myapp
--strip-base-prefix=true
Request to /myapp/api/users → forwarded as /api/users

​
Redirect Configuration

​
--redirect-domains

Environment: REDIRECT_DOMAINS
Default: unset (same domain only) Comma-separated list of allowed redirect domains. 
--redirect-domains="example.com,app.example.com,example.org"
See [Redirect Domain Configuration](redirect domains configuration) for details.

​
--public-url

Environment: PUBLIC_URL
Default: unset Externally accessible URL for this Anubis instance (used for forwardAuth with Traefik). 
--public-url=https://auth.example.com
Only set this when using forwardAuth mode. Leave unset for sidecar/standalone deployments.

​
robots.txt

​
--serve-robots-txt

Environment: SERVE_ROBOTS_TXT
Default: false Serve a default robots.txt that disallows all AI scrapers and bots. 
--serve-robots-txt=true

​
Unix Socket Configuration

​
--socket-mode

Environment: SOCKET_MODE
Default: 0770 Permissions (mode) for Unix domain sockets. 
--socket-mode=0770  # Owner and group can read/write
--socket-mode=0666  # All users can read/write
Only used when --bind-network=unix or --metrics-bind-network=unix.

​
Open Graph Configuration

​
--og-passthrough

Environment: OG_PASSTHROUGH
Default: false Enable Open Graph tag passthrough for social media previews. 
--og-passthrough=true
Prefer configuring Open Graph in the [policy file](the policy file) for more control.

​
--og-expiry-time

Environment: OG_EXPIRY_TIME
Default: 24h Cache expiration time for Open Graph tags. 
--og-expiry-time=24h
--og-expiry-time=1h

​
--og-cache-consider-host

Environment: OG_CACHE_CONSIDER_HOST
Default: false Include the hostname in Open Graph cache keys. 
--og-cache-consider-host=true

​
Advanced Target Configuration

​
--target-host

Environment: TARGET_HOST
Default: unset Override the Host header when forwarding to the target. 
--target-host=backend.internal

​
--target-sni

Environment: TARGET_SNI
Default: unset TLS SNI hostname when connecting to HTTPS backends. 
--target-sni=backend.example.com
--target-sni=auto  # Use Host header value

​
--target-insecure-skip-verify

Environment: TARGET_INSECURE_SKIP_VERIFY
Default: false Skip TLS certificate validation for HTTPS backends. 
--target-insecure-skip-verify=true
Only use this for development. Never skip TLS verification in production.

​
--target-disable-keepalive

Environment: TARGET_DISABLE_KEEPALIVE
Default: false Disable HTTP keep-alive for backend connections. 
--target-disable-keepalive=true

​
User Interface Customization

​
--webmaster-email

Environment: WEBMASTER_EMAIL
Default: unset Display a contact email on error pages. 
--webmaster-email=[email protected]

​
--use-simplified-explanation

Environment: USE_SIMPLIFIED_EXPLANATION
Default: false Use simplified language in “Why am I seeing this?” text for non-technical users. 
--use-simplified-explanation=true

​
--forced-language

Environment: FORCED_LANGUAGE
Default: unset Force a specific language instead of using the browser’s Accept-Language header. 
--forced-language=de  # German
--forced-language=fr  # French
Use ISO 639-1 language codes.

​
Utility Flags

​
--version

Environment: N/A Print Anubis version and exit. 
anubis --version

​
--healthcheck

Environment: N/A Run a health check against the running Anubis instance. 
anubis --healthcheck
Exits with code 0 if healthy, non-zero otherwise.

​
--extract-resources

Environment: EXTRACT_RESOURCES
Default: unset Extract embedded static resources to a directory. 
anubis --extract-resources=/tmp/anubis-static

​
--debug-benchmark-js

Environment: DEBUG_BENCHMARK_JS
Default: false Enable debug mode that shows challenges on every request for testing JavaScript performance. 
anubis --debug-benchmark-js=true
This is a debug tool only. Every request will receive a challenge, blocking all traffic. Use only for benchmarking client-side challenge performance.

​
Configuration via Policy Files

The following settings are configured in the YAML policy file rather than via flags:
  • Bot detection rules - Define which bots to block, challenge, or allow
  • Open Graph passthrough - Advanced social media preview configuration
  • Weight thresholds - Custom scoring thresholds for bot detection
See the following documentation for policy file configuration:

Bot Policies

Configure bot detection rules

Policy Configuration

Complete policy file structure

​
Environment Variable Examples

docker run -d \
  -e BIND=":8923" \
  -e TARGET="http://app:3000" \
  -e DIFFICULTY="4" \
  -e METRICS_BIND=":9090" \
  -e POLICY_FNAME="/config/botPolicy.yaml" \
  -e COOKIE_DOMAIN="example.com" \
  -e SLOG_LEVEL="INFO" \
  ghcr.io/techarohq/anubis:latest

​
Next Steps

Bot Policies

Configure bot detection rules

Deployment Guides

Platform-specific setup guides

Build docs developers (and LLMs) love

Get started for freeTalk to us