Configuration Reference

Complete guide to configuring Anubis via flags, environment variables, and policy files

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)

Health Check

curl http://localhost:9090/healthz

--metrics-bind-network

Environment: METRICS_BIND_NETWORK
Default: tcp

Network family for the metrics server.

Cookie Configuration

--cookie-domain

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.

--cookie-dynamic-domain

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.

--cookie-expiration-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

--cookie-prefix

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

--cookie-secure

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.

--cookie-same-site

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.

--cookie-partitioned

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=[e-mail]

--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

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