Show HN: Locus – added bulk CSV search, real SMTP checks, and lead dedup

Locus, an open-source lead-generation tool, added bulk CSV search, real SMTP email verification, and cross-session lead deduplication, according to its Show HN announcement. The self-hosted pipeline searches Google Maps listings by location and category, then runs each business through an LLM enrichment step using Gemini, OpenAI, Anthropic, or OpenRouter to find a verified contact email. Locus ships as a Docker Compose stack (app, worker, Postgres, Redis) with no hosted version, no account, and no fees, and its author notes automated collection of Google Maps data violates Google's Terms of Service.

Search a location and category, pull real business listings, enrich them with AI-verified emails. Free, open-source, bring your own keys, no account with us, no fees. Locus runs a pipeline: search a place and a category, pull the matching businesses, then run each one through an AI enrichment step that tries to find a verified email. Results land in a table you can filter, sort, export CSV, Excel, JSON , or push to a webhook. Built with Next.js App Router , Prisma and Postgres, NextAuth, BullMQ and Redis for the background worker, and a bring-your-own-key model for the search and AI providers. - Search and extraction : a location, a category, and a radius pull real Google Maps business listings, with live progress over WebSocket. - Bulk search from a CSV : upload a file of query/location pairs an optional radius per row and queue up to 50 searches at once instead of running them one at a time. - AI enrichment : each business gets run through an LLM step that tries to find and verify a real contact email from its website, alongside phone numbers pulled from the listing itself. Choose from Gemini, OpenAI, Anthropic, or OpenRouter. - Real SMTP verification : on top of the AI's answer, a genuine mailbox check MX lookup, then an SMTP handshake, nothing ever gets sent confirms an email before it's marked verified, not just an AI guess. - Optional Hunter.io lookup : add a Hunter.io key and it's checked before the website-and-AI step runs, skipping straight to a known email when Hunter already has one on file for the domain. - Cross-session matching : the same business found in two different searches gets recognized and merged, not duplicated, backfilling any missing phone or email instead of creating a second row. - History : every past search is kept with its full config snapshot. Re-run one, open a past search's results straight from the list, or select two sessions to compare their yield side by side. - Export and integrations : CSV, Excel, or JSON export, plus outbound webhooks and CRM connectors HubSpot, Salesforce . - Bring your own key, for everything : search provider, AI provider, database, Redis, the server itself. No hosted version, no vendor lock-in, nothing running that you don't control. - Built for self-hosting : a real Docker Compose stack app, worker, Postgres, Redis that's actually been cold-started and verified end to end, not just written and assumed to work. Locus pulls data from Google Maps and third-party search APIs. Automated collection of Google Maps data is against Google's Terms of Service. You are responsible for how you run this, which providers and proxies you use, and whether that is allowed where you operate. This project is provided for research and educational purposes with no warranty. See the licence. - Node.js 20+ - Docker for local Postgres and Redis or your own instances - A search provider key SerpApi, Serper.dev, or Google Places - An AI provider key Gemini, OpenAI, Anthropic, or OpenRouter for enrichment There's no hosted version of Locus. Running it, for local development or for real, is entirely up to you: your own Postgres, your own Redis, your own server or machine. Two ways to do that: This builds and runs everything, the app, the worker, Postgres, and Redis, as one stack. git clone https://github.com/<you /locus.git cd locus cp .env.example .env Fill in NEXTAUTH URL, NEXTAUTH SECRET, ENRICHMENT KEY SECRET, and INTERNAL API SECRET in .env before continuing. Docker compose refuses to start without them, on purpose. docker compose up --build -d Open the app at the NEXTAUTH URL you set http://localhost:3000 for a same-machine test , create an account, and add your provider keys in Settings. See the comments in docker-compose.yml and .env.example for what NEXT PUBLIC WS URL needs to be once this is reachable from outside your own machine it has to be a real address a browser can reach, not a Docker-internal one , and put a reverse proxy nginx, Caddy, Traefik in front for HTTPS rather than exposing the app's port directly. git clone https://github.com/<you /locus.git cd locus npm install cp .env.example .env docker compose up -d postgres redis npx prisma migrate deploy npm run dev:all Postgres comes up on port 5433, Redis on 6379, the app on 3000, the worker on 4000, all with reload on file changes. .env.example documents every variable. The ones you must set for a working install, Docker or not: | Variable | What it is | |---|---| | DATABASE URL | Postgres connection string. The compose file uses postgresql://locus:locus dev@localhost:5433/locus by default | | REDIS URL | Redis connection string for the job queue | | NEXTAUTH SECRET | Session signing secret. openssl rand -base64 32 | | NEXTAUTH URL | The app's real public URL, http://localhost:3000 for local testing | | ENRICHMENT KEY SECRET | Encrypts provider keys at rest. openssl rand -hex 32 | | INTERNAL API SECRET | Shared secret between the app and the worker. openssl rand -hex 32 | | FRONTEND ORIGIN | Origin allowed to reach the worker, http://localhost:3000 in dev | Optional: RESEND API KEY password-reset email, logs the link to the console when unset , SENTRY , NINE ROUTER BASE URL self-hosted model router , TRUST PROXY HEADERS only if a reverse proxy sits in front of this app . Once the app is running and you've created an account: 1. Add provider keys. Settings API Keys needs one business-search key SerpApi, Serper.dev, or Google Places and one AI key Gemini, OpenAI, Anthropic, or OpenRouter before anything can run. SerpApi and Serper.dev both have a free way to get started, no card required. A Hunter.io key is optional, it has a free tier 50 lookups/month and, when added, gets checked before the website-and-AI enrichment step runs.2. Run a search , one at a time on the Dashboard, or upload a CSV for several at once a query column and a location column, an optional radius column per row . Progress streams in live: businesses found, phone numbers extracted, emails verified, as they happen, not just at the end. 3. Work the results. The leads table supports filtering by status verified, needs enrichment, pending, failed , search, sort, and bulk actions. A lead that failed enrichment can be retried individually or in bulk. The same business found again in a later search gets merged into its existing lead instead of duplicated. Export whenever you want a CSV, Excel file, or JSON, or push results to a webhook or CRM connector. 4. Come back to it later. Every search lands in History with its full config snapshot radius, provider, enrichment depth . Click any past search to reopen its results, re-run it with the same settings, or select two searches to compare their yield side by side. npm run dev:all app plus worker with reload npm test Vitest unit and integration npm run test:e2e Playwright, needs the app running npx tsc --noEmit typecheck See TESTING.md for the test layers and conventions. - app/ , Next.js App Router pages and API routes - server/index.ts , the Express and BullMQ worker that runs searches and enrichment and pushes progress over WebSocket - lib/enrichment/ , provider adapters and the enrichment waterfall - lib/export/ , CSV/Excel/JSON export and the webhook/connector layer - prisma/schema.prisma , the data model See CONTRIBUTING.md . Security reports go through SECURITY.md , not public issues. AGPL-3.0-or-later. If you run a modified version as a network service, you have to make your changes available to its users. See LICENSE . Built by Cloudz Computing https://www.cloudzcomputing.com