> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/TecharoHq/Anubis/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Warning>
  Environment variable names are uppercase versions of flag names with hyphens replaced by underscores. For example, `--cookie-domain` becomes `COOKIE_DOMAIN`.
</Warning>

## Core Configuration Flags

### Network and Binding

#### `--bind`

**Environment**: `BIND`\
**Default**: `:8923`

Network address for Anubis to listen on.

```bash theme={null}
# 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`.

```bash theme={null}
--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.

```bash theme={null}
# 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.

```bash theme={null}
--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.

```bash theme={null}
--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)

<CodeGroup>
  ```bash Health Check theme={null}
  curl http://localhost:9090/healthz
  ```

  ```bash Prometheus Metrics theme={null}
  curl http://localhost:9090/metrics
  ```
</CodeGroup>

#### `--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.

```bash theme={null}
# Allow cookies for all subdomains of example.com
--cookie-domain=example.com
```

<Warning>
  Do not include a port number in `COOKIE_DOMAIN`. Unlike `REDIRECT_DOMAINS`, the cookie domain must be a bare domain name.
</Warning>

#### `--cookie-dynamic-domain`

**Environment**: `COOKIE_DYNAMIC_DOMAIN`\
**Default**: `false`

Automatically set cookie domain based on the request hostname.

```bash theme={null}
--cookie-dynamic-domain=true
```

<Warning>
  You cannot set both `COOKIE_DOMAIN` and `COOKIE_DYNAMIC_DOMAIN` at the same time.
</Warning>

#### `--cookie-expiration-time`

**Environment**: `COOKIE_EXPIRATION_TIME`\
**Default**: `168h` (7 days)

How long challenge pass cookies remain valid.

```bash theme={null}
--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.

```bash theme={null}
--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.

```bash theme={null}
--cookie-secure=true   # Require HTTPS (recommended)
--cookie-secure=false  # Allow HTTP (development only)
```

<Warning>
  If using plain HTTP, you must set `--cookie-secure=false` or cookies will be rejected by browsers.
</Warning>

#### `--cookie-same-site`

**Environment**: `COOKIE_SAME_SITE`\
**Default**: `None`

Sets the `SameSite` attribute for cookies. Valid values: `None`, `Lax`, `Strict`, `Default`.

```bash theme={null}
--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)](https://developers.google.com/privacy-sandbox/cookies/chips) flag for iframe isolation.

```bash theme={null}
--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.

```bash theme={null}
--policy-fname=/etc/anubis/botPolicies.yaml
```

For details on policy file syntax, see [Bot Policies](/admin/policy-configuration).

### Logging

#### `--slog-level`

**Environment**: `SLOG_LEVEL`\
**Default**: `INFO`

Log level for structured logging. Valid values: `DEBUG`, `INFO`, `WARN`, `ERROR`.

```bash theme={null}
--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

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

#### `--ed25519-private-key-hex`

**Environment**: `ED25519_PRIVATE_KEY_HEX`\
**Default**: Random (generated at startup)

Hex-encoded 64-character ED25519 private key for signing JWTs.

```bash theme={null}
--ed25519-private-key-hex=a1b2c3d4e5f6...  # 64 hex characters
```

Generate a key:

```bash theme={null}
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.

```bash theme={null}
--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.

```bash theme={null}
--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.

```bash theme={null}
--use-remote-address=true
```

<Warning>
  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.
</Warning>

#### `--custom-real-ip-header`

**Environment**: `CUSTOM_REAL_IP_HEADER`\
**Default**: unset

Read the client's real IP from a custom header name.

```bash theme={null}
--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.

```bash theme={null}
--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).

```bash theme={null}
--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.

```bash theme={null}
--difficulty-in-jwt=true
```

### Path Configuration

#### `--base-prefix`

**Environment**: `BASE_PREFIX`\
**Default**: unset

Global path prefix for all Anubis endpoints.

```bash theme={null}
--base-prefix=/myapp
```

With this set:

* Challenge page: `/myapp/` instead of `/`
* API endpoints: `/myapp/.within.website/x/anubis/...`

<Warning>
  `BASE_PREFIX` must start with a slash and must not end with a slash.
</Warning>

#### `--strip-base-prefix`

**Environment**: `STRIP_BASE_PREFIX`\
**Default**: `false`

Remove the base prefix when forwarding requests to the target.

```bash theme={null}
--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.

```bash theme={null}
--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).

```bash theme={null}
--public-url=https://auth.example.com
```

<Warning>
  Only set this when using forwardAuth mode. Leave unset for sidecar/standalone deployments.
</Warning>

### robots.txt

#### `--serve-robots-txt`

**Environment**: `SERVE_ROBOTS_TXT`\
**Default**: `false`

Serve a default `robots.txt` that disallows all AI scrapers and bots.

```bash theme={null}
--serve-robots-txt=true
```

### Unix Socket Configuration

#### `--socket-mode`

**Environment**: `SOCKET_MODE`\
**Default**: `0770`

Permissions (mode) for Unix domain sockets.

```bash theme={null}
--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.

```bash theme={null}
--og-passthrough=true
```

<Note>
  Prefer configuring Open Graph in the \[policy file]\(the policy file) for more control.
</Note>

#### `--og-expiry-time`

**Environment**: `OG_EXPIRY_TIME`\
**Default**: `24h`

Cache expiration time for Open Graph tags.

```bash theme={null}
--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.

```bash theme={null}
--og-cache-consider-host=true
```

### Advanced Target Configuration

#### `--target-host`

**Environment**: `TARGET_HOST`\
**Default**: unset

Override the `Host` header when forwarding to the target.

```bash theme={null}
--target-host=backend.internal
```

#### `--target-sni`

**Environment**: `TARGET_SNI`\
**Default**: unset

TLS SNI hostname when connecting to HTTPS backends.

```bash theme={null}
--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.

```bash theme={null}
--target-insecure-skip-verify=true
```

<Warning>
  Only use this for development. Never skip TLS verification in production.
</Warning>

#### `--target-disable-keepalive`

**Environment**: `TARGET_DISABLE_KEEPALIVE`\
**Default**: `false`

Disable HTTP keep-alive for backend connections.

```bash theme={null}
--target-disable-keepalive=true
```

### User Interface Customization

#### `--webmaster-email`

**Environment**: `WEBMASTER_EMAIL`\
**Default**: unset

Display a contact email on error pages.

```bash theme={null}
--webmaster-email=admin@example.com
```

#### `--use-simplified-explanation`

**Environment**: `USE_SIMPLIFIED_EXPLANATION`\
**Default**: `false`

Use simplified language in "Why am I seeing this?" text for non-technical users.

```bash theme={null}
--use-simplified-explanation=true
```

#### `--forced-language`

**Environment**: `FORCED_LANGUAGE`\
**Default**: unset

Force a specific language instead of using the browser's `Accept-Language` header.

```bash theme={null}
--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.

```bash theme={null}
anubis --version
```

#### `--healthcheck`

**Environment**: N/A

Run a health check against the running Anubis instance.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
anubis --debug-benchmark-js=true
```

<Warning>
  This is a debug tool only. Every request will receive a challenge, blocking all traffic. Use only for benchmarking client-side challenge performance.
</Warning>

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

<CardGroup cols={2}>
  <Card title="Bot Policies" icon="shield" href="/admin/policy-configuration">
    Configure bot detection rules
  </Card>

  <Card title="Policy Configuration" icon="file-code" href="/admin/policy-configuration">
    Complete policy file structure
  </Card>
</CardGroup>

## Environment Variable Examples

<CodeGroup>
  ```bash Docker theme={null}
  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
  ```

  ```bash Systemd (.env file) theme={null}
  # /etc/anubis/myapp.env
  BIND=127.0.0.1:8923
  TARGET=http://localhost:3000
  DIFFICULTY=4
  METRICS_BIND=127.0.0.1:9090
  POLICY_FNAME=/etc/anubis/myapp.botPolicies.yaml
  COOKIE_DOMAIN=example.com
  COOKIE_EXPIRATION_TIME=168h
  SLOG_LEVEL=INFO
  ED25519_PRIVATE_KEY_HEX_FILE=/etc/anubis/signing.key
  ```

  ```bash Direct Invocation theme={null}
  anubis \
    --bind=":8923" \
    --target="http://localhost:3000" \
    --difficulty=4 \
    --metrics-bind=":9090" \
    --policy-fname="/etc/anubis/botPolicy.yaml" \
    --cookie-domain="example.com" \
    --slog-level=INFO
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Bot Policies" icon="shield" href="/admin/policy-configuration">
    Configure bot detection rules
  </Card>

  <Card title="Deployment Guides" icon="rocket" href="/deployment/reverse-proxy">
    Platform-specific setup guides
  </Card>
</CardGroup>