Hermes Lead Machine Setup Guide

Use the right workflow

This setup is for public business contact discovery. Do not use it for owner lookup, founder lookup, decision-maker lookup, personal email scraping, personal phone scraping, personal LinkedIn profile scraping, or owner proof collection.

Install the requirements

Install these first on macOS or Windows.

• Python 3.11 or newer.
• Node.js 18 or newer.
• npm.
• Git.
• Chrome or Chromium.
• PowerShell plus Git Bash or WSL on Windows.

python --version
node --version
npm --version
git --version

Install and check Hermes Agent

Install Hermes first, then run setup, check the installation, and start the dashboard.

hermes --version
hermes setup
hermes doctor
hermes dashboard --port 9119 --host 127.0.0.1 --no-open

Open the dashboard in your browser.

http://127.0.0.1:9119

Connect an LLM to Hermes

Run Hermes setup and connect your preferred LLM provider. Keep real API keys in the Hermes auth flow or local environment files, not in screenshots or shared notes.

hermes setup
hermes auth add <provider>
hermes model

If your Lead Machine backend uses provider-specific environment variables, add only the values required by your local backend.

LLM_API_KEY=your_provider_key
LLM_MODEL=your_model_name

Create the Lead Machine backend

Clone or copy the backend project into your projects folder, install dependencies, and create a local .env file.

cd ~/Documents
git clone YOUR_LEAD_MACHINE_REPO_URL lead-machine-backend
cd lead-machine-backend
npm install

On Windows PowerShell, use your Documents folder.

cd $env:USERPROFILE\Documents
cd lead-machine-backend
npm install

Add backend environment values

Create .env in the backend folder. Use placeholders in public docs and replace them only on your own machine.

PORT=8788
HOST=127.0.0.1
HERMES_PUBLIC_TOKEN=change_this_token
HERMES_PORTFOLIO_NICHE=dentists
HERMES_PORTFOLIO_COUNTRY=United States
HERMES_PORTFOLIO_LOCATION=New York
HERMES_PORTFOLIO_TARGET=25
HERMES_PORTFOLIO_MIN_SCORE=45

Install discovery and enrichment tools

From the backend folder, run the included bootstrap script. It installs the vendor tools and Python environments used by the backend for discovery and public contact enrichment.

cd lead-machine-backend
bash scripts/bootstrap_tools.sh

On Windows, run the same command from Git Bash or WSL. If installation fails, confirm Python, Node.js, Git, Chrome, and Microsoft C++ Build Tools are installed.

Verify the backend

Start the backend and check health before connecting the dashboard plugin.

npm start

http://127.0.0.1:8788/api/health
http://127.0.0.1:8788/api/workflow

Install the Hermes dashboard plugin

Create the Lead Machine plugin folder inside your Hermes plugin directory, then copy the dashboard files into it.

mkdir -p ~/.hermes/plugins/lead-machine/dashboard

Copy these files into the dashboard folder.

manifest.json
plugin_api.py
dist/index.pro.js
dist/style.pro.css

Create the plugin manifest

Create manifest.json inside the plugin dashboard folder.

{
  "name": "lead-machine",
  "label": "Lead Machine",
  "description": "Business contact discovery, validation, CRM, export, and campaign control inside Hermes.",
  "icon": "Radar",
  "version": "1.2.0",
  "tab": { "path": "/lead-machine", "position": "after:plugins" },
  "entry": "dist/index.pro.js",
  "css": "dist/style.pro.css",
  "api": "plugin_api.py"
}

Point the plugin at the backend

Inside plugin_api.py, point the plugin to the backend URL. You can also use environment variables when the backend path differs by machine.

BACKEND_URL = "http://127.0.0.1:8788"

LEAD_MACHINE_BACKEND_URL=http://127.0.0.1:8788
LEAD_MACHINE_BACKEND_DIR=/absolute/path/to/lead-machine-backend

Restart Hermes and open Lead Machine

Restarting the dashboard lets Hermes discover the new plugin files and mount the plugin backend.

hermes dashboard --stop
hermes dashboard --port 9119 --host 127.0.0.1 --no-open

Open the Lead Machine tab.

http://127.0.0.1:9119/lead-machine

Run a lead search

Start with a small, clear search so you can verify results before scaling up.

The workflow finds businesses, validates location and niche fit, scrapes public pages, extracts business contact channels, removes weak rows, scores confidence, and prepares export-ready leads.

Use the backend API

You can also create and export runs through the backend API.

curl -X POST http://127.0.0.1:8788/api/runs \
  -H "Content-Type: application/json" \
  -d '{"source":"lead-scraper","niche":"dentists","location":"New York","country":"United States","target":25,"minScore":45}'

curl http://127.0.0.1:8788/api/runs
curl http://127.0.0.1:8788/api/runs/RUN_ID
curl http://127.0.0.1:8788/api/runs/RUN_ID/leads.csv

Set up campaign drafts carefully

Start in local draft mode so no real email is sent until sender configuration, testing, and compliance settings are ready.

SENDING_ENABLED=false
DAILY_LIMIT=100
PER_MINUTE_LIMIT=10

Only enable sending after you have tested SMTP or API sender settings, reviewed the lead list, and confirmed unsubscribe, suppression, and bounce handling.

Troubleshooting

• If the dashboard does not open, stop and restart hermes dashboard on port 9119.
• If the backend is offline, run npm start from lead-machine-backend.
• If tools are missing, rerun bash scripts/bootstrap_tools.sh.
• If a Python environment breaks, remove the generated virtual environment folders and rerun the bootstrap script.
• If no leads appear, try a broader niche and city, then lower the target for the first test run.
• If owner language appears, confirm the workflow source is lead-scraper and the strategy is business-contact-v2.

Clean product description

Lead Machine is a Hermes Agent workflow that finds public business leads for a niche and location, validates each business, extracts public business contact channels, scores contact confidence, and exports campaign-ready CSV leads.

Describe it as business contact discovery, public business email extraction, contact form discovery, website and social lead enrichment, and campaign-ready CSV export.