Configuration

HiveGuard has two configuration layers:

1. Environment variables — set at startup, require a restart to change
2. Runtime config — stored in Redis, editable via the dashboard or CLI without restarting

Environment variables

Set these in your .env file or Docker Compose environment.

Variable	Required	Description
TARGET_URL	yes	Upstream service to proxy requests to
DATABASE_URL	yes	PostgreSQL async connection string
SECRET_KEY	yes	Random secret for session signing (use at least 32 chars)
DASHBOARD_USERNAME	yes	Dashboard login username
DASHBOARD_PASSWORD	yes	Dashboard login password
REDIS_URL	no	Redis URL (default: redis://redis:6379)
LOG_LEVEL	no	Logging level: DEBUG, INFO, WARNING, ERROR (default: INFO)

Runtime config

These settings live in Redis and take effect immediately without a restart.

View current config

hiveguard config show

Or via the dashboard: Settings tab.

Change settings

# Risk threshold: minimum score to pass a challenge (0.0–1.0)
hiveguard config set --risk-threshold 0.7

# Consensus threshold: minimum agreement fraction (0.0–1.0)
hiveguard config set --consensus-threshold 0.6

# Proxy timeout: seconds before HiveGuard times out the upstream
hiveguard config set --proxy-timeout 30.0

# Challenge token TTL: seconds a challenge token stays valid
hiveguard config set --challenge-token-ttl 300

# Log level
hiveguard config set --log-level DEBUG

Config reference

Key	Type	Default	Description
risk_threshold	float	0.5	Minimum confidence score for a challenge response to pass
consensus_threshold	float	0.6	Fraction of solvers that must agree for a response to count
proxy_timeout	float	30.0	Seconds before timing out the upstream proxy request
challenge_token_ttl	int	300	Seconds a challenge JWT stays valid
log_level	string	INFO	Runtime log level

Proxy rules

Proxy rules control which paths require a challenge. By default, all proxied paths require a valid challenge token.

Create a rule that skips the challenge for health-check paths:

hiveguard proxy-rules create "/health" --match-type prefix --priority 10

Manage rules via the dashboard (Proxy Rules tab) or CLI (hiveguard proxy-rules).

See Protecting an API for a complete walkthrough.