Quickstart Guide #

Get Huginn running and see your first devices in 15 minutes.

Requirements #

  • Any x86_64 or aarch64 machine with 2+ GB RAM and 16+ GB storage
  • PostgreSQL 15 or later (optional but recommended for data persistence)
  • Network access to receive syslog from your gateway
  • A log source: any syslog-capable firewall or gateway (UniFi, pfSense, OPNsense, MikroTik, etc.)

Option 1: NixOS (Recommended) #

Add Huginn as a flake input and enable the service. PostgreSQL, nginx, firewall rules, and systemd are configured automatically.

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    huginn.url = "github:aletheiastrategic/huginn-nix";
  };

  outputs = { nixpkgs, huginn, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        huginn.nixosModules.default
        {
          services.huginn = {
            enable = true;
            domain = "huginn.example.com";  # or null for all hosts
          };
        }
      ];
    };
  };
}

Rebuild and switch:

sudo nixos-rebuild switch

Open http://huginn.example.com in your browser.

See the huginn-nix README for all module options.

Option 2: Linux Binary #

Download and Extract #

Download the tarball for your architecture from the downloads page:

# x86_64
curl -LO https://downloads.aletheiastrategic.com/huginn/v0.1.0/huginn-0.1.0-linux-x86_64.tar.gz
tar xzf huginn-0.1.0-linux-x86_64.tar.gz
cd huginn-0.1.0-linux-x86_64

Set Up PostgreSQL #

Huginn uses PostgreSQL to persist devices, alerts, graph data, and event logs across restarts. Without a database, Huginn runs fully in-memory and all data is lost when the process stops.

Install PostgreSQL 15+ if you don’t have it already:

# Debian/Ubuntu
sudo apt install postgresql

# Fedora/RHEL
sudo dnf install postgresql-server postgresql
sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

Create a database user and database:

sudo -u postgres createuser --pwprompt huginn
# Enter a password when prompted

sudo -u postgres createdb --owner=huginn huginn

Run the database migrations to create the required schema and tables. The tarball includes migration SQL in share/huginn/migrations/:

cd share/huginn/migrations
sqitch deploy db:pg:huginn
cd ../../..

If you don’t have Sqitch installed, you can apply the migrations directly with psql. Run each deploy script in order:

for f in share/huginn/migrations/deploy/*.sql; do
  psql -U huginn -d huginn -f "$f"
done

Configure Huginn #

Copy the example environment file and edit it:

cp share/huginn/huginn.env.example huginn.env

At minimum, set DATABASE_URL to point at your PostgreSQL instance:

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

The full connection string format is:

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

See the Configuration Reference for all available settings.

Start Huginn #

./bin/huginn --config huginn.env

Huginn loads the config file, connects to PostgreSQL, and starts listening for syslog on UDP port 514 (configurable via SYSLOG_PORT).

Note: Binding to port 514 requires root privileges or CAP_NET_BIND_SERVICE. You can either run as root, grant the capability (sudo setcap cap_net_bind_service=+ep ./bin/huginn), or use a higher port like 1514 and redirect traffic with iptables.

Set Up a Reverse Proxy #

Put nginx or Caddy in front of Huginn for TLS and static asset serving. An example nginx config is included:

sudo cp share/huginn/nginx.conf.example /etc/nginx/sites-available/huginn
# Edit the file: set server_name, SSL cert paths, and proxy_pass target
sudo ln -s /etc/nginx/sites-available/huginn /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Open https://your-server in your browser.

Running Without a Database #

If you omit DATABASE_URL from the config, Huginn runs in memory-only mode. Everything works – devices are fingerprinted, alerts fire, the dashboard updates in real time – but nothing is persisted. When the process restarts, it starts fresh.

This is useful for quick evaluation but not recommended for production.

Option 3: Docker #

Quick Start #

Clone the compose repo and start both Huginn and PostgreSQL:

git clone https://github.com/aletheiastrategic/huginn-docker.git
cd huginn-docker
cp .env.example .env
# Edit .env -- at minimum, change POSTGRES_PASSWORD
docker compose up -d

Huginn starts on http://localhost:3000. Syslog listens on UDP 514.

Pull the Image Directly #

If you already have PostgreSQL running and just want the Huginn container:

docker pull ghcr.io/aletheiastrategic/huginn:latest

docker run -d \
  --name huginn \
  -p 3000:3000 \
  -p 514:514/udp \
  -e DATABASE_URL=postgres://huginn:yourpassword@host.docker.internal:5432/huginn \
  ghcr.io/aletheiastrategic/huginn:latest

Configuration #

All settings from the Configuration Reference work as environment variables. Pass them via docker run -e or add them to the .env file when using Compose.

Persisting Data #

The compose file stores PostgreSQL data in a named volume (pgdata). To back up:

docker compose exec db pg_dump -U huginn huginn > backup.sql

Configure Your Log Source #

Point your gateway’s syslog output to Huginn’s IP on port 514/udp.

For UniFi, see the UniFi Setup Guide.

For other devices, configure standard syslog (RFC 3164 or 5424) to send to <huginn-ip>:514.

Activate Your License #

The Community tier works immediately with no license key.

For Home or Pro, upload your license key in the web UI under Settings > License, or place the license.key file alongside the binary.

Purchase a license at aletheiastrategic.com/pricing.

What Happens Next #

Huginn learns your network’s rhythms automatically. No rules to write, no thresholds to tune.

Minutes 1-15: Devices appear as firewall logs arrive. ARP discovery maps MAC-to-IP addresses. Reverse DNS resolves hostnames from your gateway’s DHCP leases. You’ll see your network populate in real time.

Hours 1-8: Each device builds a behavioral profile for the current time of day. The hourly detection layer activates first, catching sudden spikes or unusual connection patterns within the current hour.

Hours 24-48: Daily patterns emerge. Huginn learns that your office printer is quiet at night and busy during work hours, that the smart TV streams every evening, that the NAS backs up at 2am. The daily detection layer activates, catching devices that are active when they shouldn’t be.

Day 7 (full training): After one complete week, all 168 hourly slots (24 hours x 7 days) have been observed. Huginn now knows the difference between Tuesday 2pm and Saturday 3am for every device. Weekly patterns are captured: the office is quiet on weekends, the backup job runs on Sundays, the security camera uploads peak on Monday mornings.

From this point forward, anomaly detection is fully active. Any device behaving unusually for that specific time of week triggers an alert. A laptop suddenly transferring gigabytes at 3am Saturday will fire, but the same laptop doing its normal Tuesday 10am sync won’t.

Tip: Use the Simulate page to test detection immediately. The built-in attack scenarios generate realistic traffic patterns that trigger alerts without waiting for the training period. This is the fastest way to see how Huginn responds to threats on your network.