Getting Started

Five minutes to your first alert

Hellhound watches any automation you point it at. It learns what "normal" looks like over the first 10 runs, then alerts you by email or Slack the moment something looks seriously wrong.

There are two ways to connect your automations:

Install Hellhound

Install the CLI globally via npm. You need Node.js 18 or higher.

Verify it worked:

Initialize your account

Link the CLI to your Hellhound account. This generates your API key and saves it locally to ~/.hellhound/config.json.

You will be prompted for your email address. Enter the email you used to sign up.

What happens:

Hellhound creates your account (or links to your existing one) and saves your API key locally. You only need to do this once per machine.

Example output:

Monitor your first automation

Choose the connection method that matches how your automation runs.

Set up your alerts

Hellhound needs to know where to send alerts when something goes wrong. You can set up alerts per automation.

Email alerts

You can add multiple email addresses:

Slack alerts

Get a Slack incoming webhook URL:

1. Go to api.slack.com/apps
2. Create a new app or use an existing one
3. Enable Incoming Webhooks
4. Add a webhook to your workspace
5. Copy the webhook URL (starts with https://hooks.slack.com/...)

SMS alerts (Agency plan)

SMS alerts are available on the Agency plan. Phone numbers must be in E.164 format (+14155552671).

View your alert config

For Make.com / n8n / Zapier

Alert config for webhook-based automations works the same way. Use the automation_name you set in the webhook as the --name flag:

Your monitoring dashboard

Open your dashboard at hellhound.dev/dashboard.

What you see:

Agent list — every automation you are monitoring. Each shows:

• ● Green dot — actively monitored, last run normal
• ⚠ Amber dot — anomaly detected on last or recent run
• ● Red dot — crashed, dead heartbeat, or missed run

Click any agent to see its run history.

Run history

Each row shows one execution of your automation:

Click any run to see the full detail including:

• — Exact anomaly reasons
• — Which alerts were sent and when

What "anomaly" means

Anomaly means Hellhound detected something statistically unusual compared to your automation's baseline. It does NOT necessarily mean something is wrong.

When you see an anomaly:

1. Click the run to see the specific reason
2. Check if your automation actually produced correct output
3. If it was a false alarm, ignore it — the baseline will adjust

Common false alarms in the first 50 runs:

• — Your automation ran with fewer records than usual
• — The API it calls was slow
• — You ran it manually in a slightly different way

False alarms reduce significantly after 50+ runs as the baseline learns your automation's real patterns.

How Hellhound detects problems

Hellhound uses baseline learning — not rules you configure. It watches your automation run and learns what normal looks like, then alerts when something deviates significantly.

The baseline period

For the first 10 runs, Hellhound collects data but does not alert. This is the baseline learning period.

After 10 runs, it knows:

• — How long your automation normally takes
• — How much output it normally produces
• — What format the output is normally in

Every run after that is compared against this baseline.

What triggers an alert

Hellhound only alerts on extreme outliers to minimize false positives. Small day-to-day variations are ignored.

These always trigger an alert (no baseline needed):

• ●Crash — exit code not zero
• ●Error keywords — "failed", "error", "timeout" in logs

These trigger an alert after baseline is established:

• ●Output 90%+ shorter than baseline
  Example: normally 5,000 chars, now 50 chars
• ●Duration 10x+ slower than baseline
  Example: normally 30 seconds, now 5 minutes
• ●Duration 95%+ faster than usual (exit 0 only)
  Example: normally 30 seconds, now 1 second — likely crashed immediately
• ●Output format changed — was JSON, now plain text
• ●No heartbeat received — long-running agent went quiet
• ●Identical output every run — possible stuck loop
• ●No output — when baseline shows it normally produces content
• ●Missed scheduled run — silence where output was expected

What does not trigger an alert

These are intentionally ignored:

• ○Output 20%, 40%, or even 80% shorter than baseline
• ○Duration 2x or 3x slower than baseline
• ○Normal variation in output length
• ○API responses that are slightly slower

This is deliberate. Automation output varies naturally based on how much data your agents process. Hellhound only fires when something is extreme enough that no human would call it normal.

Alert deduplication

If the same automation keeps failing, Hellhound does not send you an alert for every single run. It deduplicates alerts with a 30-minute cooldown per automation per alert type.

You get alerted when something goes wrong. You do not get 47 emails because your cron job failed 47 times.

Common questions