Skip to content
Get packs

Guide · Open source

How to use Huginn: run it with Docker and build your first agent

Updated · written with AI from the project's own documentation and checked against our catalogue data

Huginn is an open-source system for building small automated helpers called Agents. They can read websites, watch RSS feeds, email and webhooks, then send notifications or take actions when something changes. This guide shows you how to start Huginn with Docker, log in, and understand how agents pass events along a chain.

Huginnhuginn/huginn · ★ 50.3k · MIT

Quick start

  1. 1Install Docker. Make sure Docker is installed and running on your machine or server.
  2. 2Start Huginn. Run the official image with the docker run command, mapping port 3000.
  3. 3Open the web interface. Visit http://localhost:3000/ in your browser.
  4. 4Log in as admin. Use the username admin and the password printed in the container log.
  5. 5Create your first agent. Add an agent that watches a source, such as a website or RSS feed.
  6. 6Link agents into a chain. Connect agents so events pass from the source agent to a notifier.
  7. 7Plan for ongoing hosting. Move to Docker Compose or another always-on setup so the worker keeps running.

What Huginn does and who it suits

Huginn is a hackable, self-hosted take on IFTTT or Zapier. You run it on your own server, so you control where your data lives. Agents create and consume events, and those events move along a directed graph that you design.

  • Scrape websites and get an email when they change
  • Watch RSS feeds, IMAP mailboxes, webhooks and MQTT topics
  • Send digest emails at set times of day
  • Post to Slack, Telegram and other services, or send SMS with Twilio
  • Write custom logic in JavaScript, Liquid templates or jq

Install Huginn with Docker

The quickest way to try Huginn is the official Docker image, which runs everything in one container. The only prerequisite listed is Docker. Run the command below, then open http://localhost:3000/ in your browser.

  • Prerequisite: Docker installed on your machine
  • Port 3000 is mapped to your computer so you can reach the web interface
docker run -it -p 3000:3000 ghcr.io/huginn/huginn

Log in for the first time

Log in as admin. The password is printed once in the container log, so check the output of the container if you did not record it. The Docker documentation covers persistent storage, an external database and the multi-container image for longer-term use.

  • Username: admin
  • Password: printed once in the container log

Understand agents and event chains

An agent does one job, such as reading a feed or checking a web page. When it finds something, it creates an event. You link agents so that events flow from one to the next, for example from a website scraper to an email notifier. Start with a simple two-agent chain before building longer ones.

Run Huginn for ongoing use

Huginn runs as a web process plus a background worker, backed by MySQL or PostgreSQL. The README recommends Docker Compose on your own server for production. Agents only keep working while the worker is running, so a host that sleeps or stops background processes will stop your automations.

  • Recommended for production: Docker Compose on your own server
  • Other options listed: Dokku, managed platforms, YunoHost, Unraid and a manual install on Ubuntu or Debian
  • Free tiers on managed platforms generally do not keep a worker running

Develop Huginn locally

If you want to change Huginn itself, the README describes a local setup. You fork the repository, copy the example environment file, make sure MySQL or PostgreSQL is installed, then install dependencies and create the database. Set APP_SECRET_TOKEN in your .env file before you start.

  • Copy .env.example to .env and update APP_SECRET_TOKEN
  • Install MySQL or PostgreSQL first
  • Development emails open at http://localhost:3000/letter_opener by default
cp .env.example .env

What people use it for

  • Get an email when a web page you follow changes
  • Watch an RSS feed and forward new items to Slack or Telegram
  • Receive a digest email with selected items at a set time each day
  • Publish your own RSS feed or JSON endpoint from events your agents collect
  • Log your location over time on your own server

Frequently asked questions

How do I install Huginn?

The README's quickest method is the official Docker image. Run docker run -it -p 3000:3000 ghcr.io/huginn/huginn, then open http://localhost:3000/. Docker is the only prerequisite listed for this method.

Is Huginn free?

Huginn is released under the MIT licence, which is listed on the project page. You can run it yourself, but you still pay for any server or hosting you use to keep it running.

What do I need to run Huginn?

For the Docker method you need Docker. For a longer-term setup the README describes a web process plus a background worker, backed by MySQL or PostgreSQL. A worker must keep running for agents to work.

What is the default login for Huginn?

The username is admin. The password is printed once in the container log when the image starts, so check the output if you did not save it.

Is Huginn a good alternative to IFTTT or Zapier?

The project describes itself as a hackable version of IFTTT or Zapier that runs on your own server. It suits people who want to keep their data on their own machine, but it needs more setup than a hosted service. Comparable self-hosted projects mentioned include n8n, Node-RED and Activepieces.

Why are my Huginn agents not running?

Agents depend on a background worker. The README notes that a worker must keep running, and free tiers on many platforms do not keep one alive. Check that your worker process or container is running.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Huginn suits people comfortable with Docker or a small Rails and background-worker setup who want IFTTT-style automation on their own server. If you want a simple one-click cloud service or guaranteed uptime without maintaining a server, a hosted tool or a self-hosted option with an easier setup will fit better.

Install options & downloads