# Huginn

> Build agents that monitor and act on your behalf.

- Category: Message Queues & Brokers
- Difficulty: intermediate
- Components: huginn, mysql
- Tags: huginn, agents, automation, monitoring
- Source: https://docker.recipes/messaging/huginn

## Overview

Huginn is an open-source automation platform that enables users to build intelligent agents that monitor websites, APIs, and data sources, then perform actions based on specific triggers and conditions. Originally created as a self-hosted alternative to commercial services like IFTTT and Zapier, Huginn provides granular control over data flows and automation workflows without relying on third-party services or API limitations. The platform operates on an agent-based architecture where each agent performs a specific function, from web scraping and RSS monitoring to sending notifications and processing data transformations.

This Huginn deployment pairs with MySQL 8.0 to provide a robust, scalable foundation for complex automation workflows. MySQL serves as the persistent storage layer for agent configurations, event histories, and workflow states, while Huginn's web interface runs on port 3000 for agent management and monitoring. The combination allows for sophisticated multi-step automation scenarios where agents can pass data between each other, creating powerful workflow chains that can handle everything from simple RSS-to-email notifications to complex data processing pipelines involving multiple APIs and services.

This stack is ideal for power users, system administrators, and organizations seeking complete control over their automation workflows without vendor lock-in or API rate limits. Unlike cloud-based automation services, this self-hosted approach provides unlimited agent creation, custom scheduling, and the ability to process sensitive data entirely within your own infrastructure, making it particularly valuable for privacy-conscious users and enterprise environments with strict data governance requirements.

## Features

- Agent-based automation architecture with 50+ built-in agent types including RSS, web scraping, email, webhooks, and API integrations
- Visual scenario builder for creating complex multi-step workflows that chain agents together with conditional logic
- Real-time event streaming and processing with configurable scheduling from minutes to months
- Custom JavaScript execution environment for data transformation and advanced logic operations
- Web-based management interface with agent monitoring, event logging, and debugging tools
- MySQL-powered event history and agent state persistence with configurable retention policies
- Built-in credential management system for securely storing API keys and authentication tokens
- Liquid templating engine for dynamic content generation and data formatting across agents

## Use cases

- Home automation monitoring by tracking IoT device APIs and triggering notifications or actions based on sensor readings
- Competitive intelligence gathering through automated web scraping of competitor websites and price monitoring
- Social media content aggregation and cross-posting by monitoring multiple platforms and reposting relevant content
- IT infrastructure monitoring with custom agents that check service availability and send alerts via multiple channels
- E-commerce inventory management by monitoring supplier APIs and automatically updating product availability
- Research and journalism workflows that track news sources, filter content, and compile reports automatically
- Personal productivity automation including email filtering, calendar management, and task creation from various triggers

## Prerequisites

- Docker and Docker Compose installed with at least 2GB available RAM for MySQL and Huginn containers
- Port 3000 available for Huginn web interface access and basic understanding of web-based administration
- Environment variables configured for database credentials including DB_NAME, DB_USER, DB_PASSWORD, and DB_ROOT_PASSWORD
- Basic knowledge of agent concepts, webhooks, and API interactions for effective automation workflow creation
- Understanding of Liquid templating syntax for advanced data transformation between agents
- Familiarity with cron-like scheduling expressions for configuring agent execution intervals

## docker-compose.yml

```yaml
services:
  huginn:
    image: huginn/huginn:latest
    container_name: huginn
    restart: unless-stopped
    environment:
      MYSQL_PORT_3306_TCP_ADDR: mysql
      HUGINN_DATABASE_NAME: ${DB_NAME}
      HUGINN_DATABASE_USERNAME: ${DB_USER}
      HUGINN_DATABASE_PASSWORD: ${DB_PASSWORD}
    ports:
      - "3000:3000"
    depends_on:
      - mysql
    networks:
      - huginn

  mysql:
    image: mysql:8.0
    container_name: huginn-mysql
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: ${DB_NAME}
      MYSQL_USER: ${DB_USER}
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - huginn

volumes:
  mysql_data:

networks:
  huginn:
    driver: bridge
```

## .env

```bash
DB_ROOT_PASSWORD=rootpassword
DB_NAME=huginn
DB_USER=huginn
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://github.com/huginn/huginn/wiki
- Web UI at http://localhost:3000, default: admin / password
- Create agents that watch for events and trigger actions
- Agent types: RSS, web scraping, email, webhooks, Twitter, etc.
- Scenarios chain agents together for complex workflows
- Self-hosted IFTTT/Zapier alternative with full control

## Troubleshooting

- Database connection failed error: Ensure MySQL container is fully initialized before Huginn starts by checking mysql logs and verifying database credentials match environment variables
- Agent execution timeout or memory errors: Increase Docker container memory limits and adjust Huginn's DELAYED_JOB_MAX_RUNTIME environment variable for long-running agents
- Web scraping agents returning empty results: Check if target websites require user agents or headers, and configure agent options with appropriate browser simulation settings
- Webhook agents not receiving data: Verify firewall rules allow incoming connections on port 3000 and check agent URLs are correctly formatted with proper authentication
- High CPU usage during agent execution: Review agent scheduling intervals and consider spreading execution times to avoid concurrent resource-intensive operations
- MySQL storage growing too large: Configure event retention policies through Huginn admin interface and set up automated cleanup for old event data

