OCI Artifact - Deploy directly from GitHub Container Registry

Huginn is a system for building agents that perform automated tasks for you online. It can read the web, watch for events, and take actions on your behalf. Think of it as a hackable IFTTT or Zapier running on your own server.

This is a Docker Compose OCI artifact, not a traditional Docker image. It contains a complete docker-compose.yml configuration that you can deploy directly using Docker 25.0+.

# 1. Create environment file
cat > .env.huginn << 'EOF'
COMPOSE_PROJECT_NAME=huginn
SERVICE_DOMAIN=huginn.example.com
DB_PASS=Swordfish
EOF

# 2. Deploy
bc huginn up

# 3. Check status
bc huginn ps

Note: Install the bc CLI with: curl -fsSL https://raw.githubusercontent.com/beevelop/beecompose/main/scripts/install.sh | sudo bash

# 1. Create environment file
cat > .env.huginn << 'EOF'
COMPOSE_PROJECT_NAME=huginn
SERVICE_DOMAIN=huginn.example.com
DB_PASS=Swordfish
EOF

# 2. Deploy from GHCR
docker compose -f oci://ghcr.io/beevelop/huginn:latest --env-file .env.huginn up -d --pull always

# 3. Check status
docker compose -f oci://ghcr.io/beevelop/huginn:latest --env-file .env.huginn ps

• Docker 25.0+ (required for OCI artifact support)
• Docker Compose v2.24+
• Traefik reverse proxy (see traefik)

This service includes all required backing stores:

See Service Dependency Graph for details.

1. Access the UI: Navigate to https://huginn.example.com
2. Login with defaults:
   • Username: admin
   • Password: password
3. Change admin password: Go to Account → Edit Account immediately after login
4. Create your first agent: Click "New Agent" and choose from available types:
   • Website Agent: Monitor websites for changes
   • RSS Agent: Parse RSS/Atom feeds
   • Webhook Agent: Receive webhooks from external services
   • Email Agent: Send email notifications
   • Trigger Agent: React to events based on conditions
5. Build agent scenarios: Chain agents together to create automation workflows
6. Set invitation code: Configure INVITATION_CODE to control user registration

bc huginn logs -f     # View logs
bc huginn restart     # Restart
bc huginn down        # Stop
bc huginn update      # Pull and recreate

# Define alias for convenience
alias dc="docker compose -f oci://ghcr.io/beevelop/huginn:latest --env-file .env.huginn"

# View logs
dc logs -f

# Restart
dc restart

# Stop
dc down

# Update
dc pull && dc up -d

# Access Rails console
docker exec -it huginn bash -c "bundle exec rails console"

# Run background jobs manually
docker exec -it huginn bash -c "bundle exec rails runner 'Agent.receive!'"

1. Create a Website Agent with:
   • URL: https://example.com/page-to-monitor
   • Mode: on_change
   • Extract: CSS selectors for content

1. Create an RSS Agent with:
   • URL: https://example.com/feed.xml
   • Expected update period: 1 day

1. Create an Email Agent or Pushover Agent that receives events from other agents

Huginn runs background jobs automatically. Check the delayed job worker:

docker exec -it huginn bash -c "ps aux | grep delayed"

Verify the system clock is correct and check agent logs in the web interface.

Ensure PostgreSQL is healthy before Huginn starts:

dc logs huginn-postgres

Check logs with dc logs huginn and ensure all required environment variables are set.

• Official Documentation
• GitHub Container Registry
• GitHub