Configuration Reference #

Huginn is configured through environment variables. You can set them directly in your shell, in a .env file loaded with source, or in a config file passed via the --config flag:

./bin/huginn --config /etc/huginn/huginn.env

The config file uses KEY=VALUE format with # comments. Environment variables set in the shell take precedence over values in the config file.

Database #

Variable	Default	Description
`DATABASE_URL`	(none)	PostgreSQL connection string. If unset, Huginn runs in memory-only mode with no persistence.

The connection string format is:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE

Example:

DATABASE_URL=postgresql://huginn:s3cret@localhost:5432/huginn

Huginn uses the siem schema inside your database. All tables are created by the migration scripts that ship with the tarball.

What the Database Stores #

Data	Without DB	With DB
Devices and fingerprints	In memory, lost on restart	Persisted and restored on startup
Alerts	In memory, lost on restart	Persisted and restored on startup
Knowledge graph	In memory, lost on restart	Persisted and restored on startup
Raw event logs	Ring buffer (last ~8,000 events)	Full history, searchable, retained per `LOG_RETENTION_DAYS`
Behavioral baselines	Rebuilt from scratch each restart	Rebuilt from scratch (baselines are always in-memory)

Server #

Variable	Default	Description
`PORT`	`3000`	HTTP API listen port.
`HOST`	`0.0.0.0`	HTTP API bind address. Use `127.0.0.1` to accept only local connections (recommended when behind a reverse proxy).
`SYSLOG_PORT`	`514`	UDP port for the syslog listener. Ports below 1024 require root or `CAP_NET_BIND_SERVICE`.
`APP_ENV`	`development`	Set to `production` for production deployments. Controls SPA asset serving and logging verbosity.
`CORS_ORIGINS`	`http://localhost:5173`	Comma-separated list of allowed CORS origins. Set this to your dashboard URL in production.
`AUTH_DISABLED`	`false`	Set to `true` to disable authentication entirely. All API endpoints become accessible without a session. Useful for single-user appliances on a trusted LAN where login is unnecessary.

Authentication #

On first launch with a database configured, Huginn shows a setup page to create the initial admin account. All subsequent access requires signing in with username and password.

Sessions are stored in PostgreSQL and last 24 hours. Passwords are hashed with PBKDF2-HMAC-SHA256 (100,000 iterations).

To skip authentication entirely, set AUTH_DISABLED=true. This is appropriate for:

Single-user appliances behind a firewall
Development and testing
Deployments where the reverse proxy handles authentication

When auth is disabled, all API endpoints are accessible without credentials and no login page is shown.

Detection Tuning #

These control the sensitivity of Huginn’s detection engines. The defaults work well for most networks. Adjust them if you’re seeing too many or too few alerts.

Variable	Default	Description
`ANOMALY_THRESHOLD`	`0.5`	Minimum surprise score (0.0-1.0) for a behavioral anomaly to generate an alert. Lower values produce more alerts.
`LEARNING_DAYS`	`7`	Number of days Huginn observes a device before its behavioral baseline is considered stable. No anomaly alerts fire during the learning period.
`ACTIVATION_DECAY`	`0.6`	Energy decay factor per hop in the spreading activation graph. Lower values make correlations more local; higher values spread further.
`COLLISION_MIN_WAVES`	`2`	Minimum number of independent activation waves that must converge on a graph node before a collision alert fires. Higher values reduce false positives but may miss simpler attack chains.

Retention #

Variable	Default	Description
`LOG_RETENTION_DAYS`	`30`	Number of days to retain raw event logs in PostgreSQL. Older events are purged automatically. Only applies when a database is configured.
`MAX_DEVICES`	`200`	Soft device limit. The Community tier is capped at 25 devices, Home at 200, Pro at unlimited. This value is overridden by your license key.

Full Example Config File #

# Required
DATABASE_URL=postgresql://huginn:changeme@localhost:5432/huginn

# Server
PORT=3000
HOST=0.0.0.0
SYSLOG_PORT=514
APP_ENV=production
CORS_ORIGINS=https://huginn.example.com
# AUTH_DISABLED=true  (uncomment to skip login on a trusted LAN)

# Detection (defaults are fine for most networks)
# ANOMALY_THRESHOLD=0.5
# LEARNING_DAYS=7
# ACTIVATION_DECAY=0.6
# COLLISION_MIN_WAVES=2

# Retention
LOG_RETENTION_DAYS=90
# MAX_DEVICES=200  (overridden by license key)

Command-Line Options #

Flag	Description
`-c`, `--config <path>`	Load environment variables from a config file. Shell environment takes precedence over file values.
`-h`, `--help`	Print usage information and exit.
`-v`, `--version`	Print version and exit.