Практические рецепты
Рабочие команды для реальных задач — копируйте, вставляйте, адаптируйте. Каждый рецепт идёт от распространённого воркфлоу и показывает точную команду и ожидаемый результат.
Working commands for real autonomous worker jobs — copy, paste, adapt. Each recipe starts from a common workflow and shows the exact command plus what to expect.
Quick Start Recipes
Four commands to get productive in under five minutes. Run a search, watch for changes, push to CRM, and recover from failures.
Run a first research pass
fathom run "Find CTOs at 50-200 person fintech startups in London, verify emails"Start with a focused query and one region/sector. Findings land in ./research-output/ with sources baked in.
Re-run and alert on changes
fathom run "..." --repeat 3600Optional watch mode re-runs every 3600s. Diffing and email / Telegram / webhook notifications require the corresponding integrations to be configured.
Push a verified list to CRM
fathom contacts push-crmSyncs contacts.db to amoCRM / Bitrix24 / HubSpot when those integrations are configured. Review the resulting CRM records according to your provider's matching policy.
Recover a crashed campaign
fathom resumeFind interrupted sessions, keep completed sub-agents, re-run the pending ones, and finish synthesis.
OSINT & Lead Generation Recipes
Find, enrich, and verify contacts at scale. These recipes cover the full pipeline from raw search to verified, enriched lead lists ready for outreach.
Find CTOs at fintech startups in London
fathom run "Find all CTOs and VP Engineering at fintech startups in London with 10-200 employees. Verify each email address. Include company size, funding stage, and tech stack." -o ./leads/london-fintech-ctosThe agent will search LinkedIn, Crunchbase, and company websites. Email verification runs via MX check and SMTP probe. Results include confidence scores for each contact.
Marketing directors at SaaS companies in Berlin
fathom run "Search for marketing directors and CMOs at SaaS companies headquartered in Berlin. Enrich each person with LinkedIn profile URL, current role tenure, and recent posts."Enrichment flags pull additional data from each source. LinkedIn enrichment grabs headline, summary, and recent activity without scraping — uses public API data.
Monitor news about a competitor
fathom run "Monitor all news, press releases, blog posts, and social mentions about Acme Corp. Alert me on funding announcements, executive changes, product launches, and partnership deals." --repeat 1800Watch mode keeps the session alive and re-checks sources every 30 minutes. The diff engine compares new results against prior runs and only alerts on genuinely new items.
Build supplier list from business directories
fathom run "Build a comprehensive list of industrial valve suppliers in the Gulf Cooperation Council region. Scrape business directories, trade association member lists, and exhibition exhibitor pages. De-duplicate by company name and website."Directory scraping respects robots.txt and rate limits automatically. Review repeated company names and URLs before using the list.
Find decision-makers at recently funded companies
fathom run "Find decision-makers (CEO, CTO, VP Sales, VP Engineering) at B2B SaaS companies that raised Series A or B in the past 90 days in the US. Include funding amount, lead investor, and hiring signals." -o ./leads/fresh-fundedCross-references Crunchbase funding data with LinkedIn job titles. Hiring signals detected from careers pages and job board postings. Sorted by funding date descending.
Search social media for technology mentions
fathom run "Search Twitter/X, Reddit, Hacker News, and dev.to for people actively discussing Apache Kafka in production. Extract author profiles, engagement metrics, and company affiliations where available."Social search covers public posts only. The agent identifies technical practitioners vs. marketers by analyzing post content and engagement patterns. Results include permalink to each source.
Parse conference speaker list and enrich
fathom run "Parse the speaker list from https://kccnceu2025.sched.com. For each speaker, find their current company, title, LinkedIn, Twitter, email (if public), and recent publications or talks." -o ./speakers/kccn-eu-2025The agent crawls the schedule page, extracts speaker names and bios, then enriches each person in parallel. Rate limiting is handled per-domain automatically.
Find companies using a specific tech stack
fathom run "Find companies in the EU that are using Rust in production. Cross-reference job postings mentioning Rust, GitHub organizations with active Rust repos, conference talks, and blog posts about Rust adoption. Identify CTOs and principal engineers."Tech stack detection uses multiple signals: job postings, GitHub activity, blog posts, Stack Overflow jobs, and conference talks. Confidence scoring weights each signal independently.
Research & Analysis Recipes
Go beyond lead generation. These recipes perform deep investigations into companies, people, supply chains, and markets — with structured, citable outputs.
Deep-dive: company tech stack and team
fathom run "Perform a deep-dive analysis of Stripe's technology stack. Map all technologies, frameworks, and infrastructure used. Identify key engineers, their backgrounds, and open-source contributions. Include blog posts about architecture decisions." -o ./analysis/stripe-techDeep mode uses more sub-agents and longer context windows. The agent triangulates from multiple sources: GitHub, engineering blogs, job postings, conference talks, and Stack Overflow activity.
Compare 5 competitors across 20 dimensions
fathom run "Compare Datadog, New Relic, Dynatrace, Splunk, and Grafana Labs across these 20 dimensions: pricing model, free tier limits, APM capabilities, log management, infrastructure monitoring, alerting, dashboarding, API quality, SDK languages, cloud integrations, on-prem options, compliance certs, market share, revenue growth, employee count, engineering team size, open-source contributions, community size, documentation quality, and enterprise features." -o ./competitive/comparisonThe agent structures each dimension as a separate sub-task for parallel execution. The table output formats findings into a structured comparison grid with confidence indicators.
Track regulatory changes in an industry
fathom run "Track all regulatory changes, proposed rules, enforcement actions, and guidance documents in the US fintech/payments space over the past 30 days. Cover CFPB, OCC, FDIC, FinCEN, SEC, and state-level regulators. Classify each by impact level and affected business models." --repeat 86400Regulatory monitoring requires reliable source tracking. The agent monitors .gov RSS feeds, Federal Register API, and regulatory news outlets. Daily re-runs detect new filings and classify them.
Analyze GitHub repository contributors
fathom run "Analyze the top 50 contributors to the vercel/next.js GitHub repository. For each contributor, find their current employer, LinkedIn profile, Twitter account, personal website, other notable open-source projects, and conference speaking history." -o ./oss/nextjs-contributorsGitHub API is used for contributor data; enrichment pulls from public profiles. The agent handles GitHub rate limits with automatic token rotation if GITHUB_TOKEN is set.
Research a person's full public footprint
fathom run "Research the full public footprint of Satya Nadella. Compile: career history, education, published articles, conference keynotes, podcast appearances, patent filings, board memberships, philanthropic activities, and social media presence. Cross-reference across LinkedIn, Wikipedia, news archives, and SEC filings." -o ./people/satya-nadellaPerson research synthesizes data from 15+ source categories. The agent respects privacy boundaries — only publicly available information is included. Sources are cited for every claim.
Investigate a supply chain
fathom run "Map the supply chain of Tesla's battery production. Identify primary cell suppliers (CATL, Panasonic, BYD), their raw material suppliers (lithium, cobalt, nickel miners), processing facilities, and logistics partners. Flag any single-source dependencies or geopolitical risks." -o ./supply-chain/tesla-batterySupply chain mapping uses SEC filings (10-K supplier disclosures), trade databases, shipping records, and industry reports. The agent builds a hierarchical supplier tree with risk annotations.
Monitor job postings for strategy signals
fathom run "Monitor job postings at Databricks, Snowflake, and dbt Labs over the past 60 days. Classify each posting by department, seniority, and technology. Detect hiring surges, new team formations, and technology adoption signals. Compare hiring velocity across the three companies." --repeat 86400 -o ./signals/hiring-trendsJob posting analysis reveals strategic intent before public announcements. The agent classifies roles by team/function and tracks velocity changes. A hiring surge in a new area often precedes product launches.
Memory & Knowledge Recipes
Build persistent knowledge across sessions. The memory graph stores entities, facts, and relationships that compound over time — making each new session smarter than the last.
Build a knowledge base from research sessions
fathom memory distill --session latestDistills facts from the latest session into the configured memory graph. Memory commands require the memory subsystem to be enabled in configuration.
Search memory for company facts
fathom memory search "Stripe"Searches the memory graph for all facts related to Stripe. Results include facts from every past session, ranked by recency and confidence. Useful for quickly recalling prior research.
Distill session facts into permanent knowledge
fathom memory distill --session latestDistillation promotes run-scoped facts into structured agent-scope knowledge. The distilled knowledge persists beyond session cleanup; review contradictory findings explicitly.
Run garbage collection on stale memories
fathom memory gc --ttl-days 90 --dry-runDry-run mode shows what would be archived without actually deleting. Memory maintenance is optional and follows the configured TTL and confidence thresholds.
Use memory to map relationships
fathom memory listLists all facts, entities, and relationships in the memory graph. Use grep or pipe to other tools for filtering.
Create a topic digest and inject into next session
fathom memory distill --session latestUse the semantic memory digest in the worker context to bootstrap a follow-up session with prior knowledge. Topic-specific retrieval is handled by the memory tools.
Persistent coworkers & schedules
Use the authenticated control plane to create durable worker profiles, connect channels and schedule recurring operations. These routes are backed by the current server API.
Create a persistent coworker
curl -X POST http://localhost:8080/api/v1/coworkers \
-H "Content-Type: application/json" \
-d '{"name":"market-watch","title":"Market watcher","role":"analyst","prompt":"Monitor the assigned market and summarize changes.","active":true}'Coworkers persist identity, role and prompt in the server database. Link channels and schedules through the authenticated API.
Schedule a coworker task
curl -X POST http://localhost:8080/api/v1/schedules \
-H "Content-Type: application/json" \
-d '{"coworker_id":"","cron_expression":"0 9 * * 1-5","timezone":"UTC","query":"Review new market signals","enabled":true}' Schedules are optional and require a coworker, validated cron expression, timezone and query. The scheduler claims due rows atomically; an external/operator scheduler must launch the claimed work.
Automation & Watch Mode Recipes
Set up always-on monitoring and batch workflows. Watch mode re-runs sessions on a schedule, diffs results, and sends alerts only when something new appears.
Daily monitoring loop for new leads
fathom run "Find new VP-level executives at Series B+ fintech companies in EMEA who joined in the past 24 hours." --repeat 86400The session persists across restarts. Configure notifications and review each run's findings before acting on changes.
Test a configured notification channel
curl -X POST http://localhost:8080/api/v1/notifications/test \
-H "Content-Type: application/json" \
-d '{"channel":"webhook"}'The endpoint accepts only a symbolic channel name (webhook, email or telegram) and uses server-side [notifications] configuration. Destinations and credentials are never supplied by the caller.
Telegram alerts for new verified contacts
fathom config set alerts.telegram.bot-token "123456:ABC..." && fathom config set alerts.telegram.chat-id "-1001234567890" && fathom run "..."Set Telegram bot token and chat ID once, then any session can send alerts to the channel. Alerts include contact name, company, email, and a link to the full result in the dashboard.
Run multiple research tasks
fathom run "Task 1: Research company A" -o ./results/task1
fathom run "Task 2: Research company B" -o ./results/task2Run multiple research tasks sequentially or in parallel.
Schedule recurring research with cron
# Standard cron scheduling
# Runs the batch file at 09:00 on weekdays
# Output folders are date-stamped. Combine with webhook notifications to get Slack/email alerts when the batch completes.Standard cron scheduling. Runs the batch file at 09:00 on weekdays. Output folders are date-stamped. Combine with webhook notifications to get Slack/email alerts when the batch completes.
API & Integration Recipes
Integrate Fathom into your existing workflows. Create sessions via REST, stream results via SSE, approve operations, and connect to external tools.
Create session via REST API and stream SSE
curl -sS -X POST http://localhost:8080/api/v1/sessions \
-H "Content-Type: application/json" \
-d '{"query":"Find CTOs at fintech startups in London"}' \
| jq -r '.id' \
| xargs -I{} curl -N http://localhost:8080/api/v1/sessions/{}/eventsFirst call creates the session and returns the session_id. Second call opens an SSE stream that yields real-time progress, sub-agent results, and the final synthesis. Each event is a JSON object.
Answer an agent's question programmatically
curl -X POST http://localhost:8080/api/v1/sessions/{session_id}/answer \
-H "Content-Type: application/json" \
-d '{"request_id":"ctrl_001","text":"Yes, proceed with verification."}'When an agent hits an approval gate or needs input, it pauses and exposes the question via the SSE stream. POST an answer to resume. Useful for building custom UIs or automated decision flows.
Approve tool calls via the API
curl -X POST http://localhost:8080/api/v1/sessions/{session_id}/approve \
-H "Content-Type: application/json" \
-d '{"request_id":"ctrl_042","approved":true}'Tool approval is an optional safety gate. When enabled, agents pause before executing side-effect tools (CRM push, email send, etc.). The API lets you build approval queues and approve or deny pending operations by request_id.
Export contacts to CSV via CLI
fathom contacts export --format csv --output ./contacts-export/Exports the full contact database to CSV. Use --output to choose the destination directory.
Connect MCP server to Claude Desktop
# Add to claude_desktop_config.json:
# {
# "mcpServers": {
# "fathom": {
# "command": "fathom",
# "args": ["mcp-serve"]
# }
# }
# }
fathom mcp-serveThe MCP server exposes all research tools to Claude Desktop via stdio. Once configured, Claude can create sessions, search contacts, manage memory, and run research tasks directly.
Build a custom dashboard using health/metrics
curl http://localhost:8080/health && echo "---" && curl http://localhost:8080/metrics/health returns component status (database, agents, memory). /metrics returns Prometheus-compatible metrics: active sessions, contacts found, memory usage, sub-agent counts, and API latency histograms.
Advanced Configuration Recipes
Fine-tune the agent system for your exact workflow. Switch profiles, route models by role, add approval gates, run parallel agents, and hook into the lifecycle.
Switch between hunter/analyst/validator profiles
fathom run "..." --profile hunter
fathom run "..." --profile analyst
fathom run "..." --profile validatorProfiles are named presets that set model, tools, temperature, and approval policies. Hunter mode maximizes coverage. Analyst mode prioritizes depth and synthesis. Validator mode focuses on fact-checking and email verification.
Role-based model routing
fathom config set agent.role_models.writer "openai/gpt-4o"
fathom config set agent.role_models.researcher "deepseek/deepseek-chat"
fathom config set agent.role_models.verifier "openai/gpt-4o-mini"Route different agent roles to different models. Writers use GPT-4o for polished output. Researchers use DeepSeek for cost-effective long-context exploration. Verifiers use GPT-4o-mini for fast checks.
Set up approval gates for sensitive operations
fathom config set agent.approval_tools '["crm_push","email_send","webhook_post"]'
fathom run "..."Approval gates pause the agent before executing sensitive tools.
Configure multi-process mode for parallel agents
fathom config set agent.max_agents 8
fathom run "Research 50 companies across 10 sectors..."Multi-process mode spawns independent agent processes that communicate via the shared contact DB and memory graph.
Tune context window and compaction thresholds
fathom config set context.context_window 128000
fathom config set context.compact_threshold 0.85When context usage hits 85% of the max, the compaction engine kicks in.
Set up hooks for custom pre/post processing
# .fathom/hooks.yaml
# hooks:
# pre-session:
# - command: ./scripts/enrich-from-db.sh
# args: ["{{session_id}}"]
# post-session:
# - command: ./scripts/push-to-warehouse.sh
# args: ["{{session_id}}", "{{output_dir}}"]Hooks run shell commands at key lifecycle points. Pre-session hooks can inject data into the agent's context. Post-session hooks can push results to data warehouses, trigger notifications, or update external systems.
Troubleshooting Recipes
When things go wrong. These recipes cover session recovery, stall debugging, memory repair, rate limit handling, and context overflow recovery.
Resume a crashed session
fathom resume # picks up the most recent interrupted sessionThe resume command inspects the session log, identifies which sub-agents completed, and re-runs only the pending ones. Final synthesis is re-triggered automatically. No data is lost.
Debug agent stalling with stall detection
RUST_LOG=debug fathom run "..."Debug logging shows every tool call, context usage, and decision point. Check logs at ~/.fathom/logs/.
Fix memory database corruption
fathom memory distill --session latestDistill facts from a persisted session into the configured memory graph; enable memory in configuration first.
Handle rate limiting from search backends
fathom config set search.backend "hybrid"Rate limits are applied per-domain. The hybrid backend spreads queries across configured providers, and the agent shifts to alternative sources when one is consistently rate-limited.
Recover from context window overflow
fathom config set context.compact_threshold 0.7When a session exceeds the context window, compact-and-retry compresses the history and resumes. A lower threshold compacts earlier and leaves more headroom.
Fix stuck session that won't complete
fathom sessions list
fathom resumeInspect stored sessions, then resume the most recent interrupted session. Resume picks up from the last checkpoint and skips already-completed sub-agents.
Clear corrupted contacts database
cp contacts.db contacts.db.bakAlways back up before repair.
Debug authentication failures
fathom config showShows all configured API keys and tokens (values are masked).
Investigate high memory usage
fathom memory stats
fathom memory gc --ttl-days 30Memory stats reports store counts. GC archives stale entries according to the configured TTL; both commands require memory to be enabled.
Export & Reporting Recipes
Turn research results into actionable formats. Export contacts to CRMs, generate PDF reports, pipe data to warehouses, and create visualizations from the memory graph.
Export contacts to HubSpot CSV format
fathom contacts export --format csv --output ./hubspot-import/Exports contacts to CSV format.
Generate a Markdown research report
fathom run "Analyze the European EV charging market: size, growth, key vendors" -o ./report/Compiles session findings into a structured Markdown report with executive summary, findings, sources, and confidence scores.
Export to JSON for programmatic processing
fathom config set export.format json
fathom run "Your task" -o ./results/JSON export includes all fields, nested objects for enrichment data, and source arrays.
Create a PDF report from session results
fathom config set export.format pdf
fathom run "Your task" -o ./results/PDF generation renders the same report structure; it requires pandoc on the host.
Export contacts as a spreadsheet
fathom contacts export --format xlsx -o ./exports/xlsx opens directly in Google Sheets and Excel; csv works everywhere.
Bulk export contacts for a data warehouse
fathom config set export.format json
fathom contacts export --format json -o ./warehouse/JSON export includes every stored field for ingestion into your warehouse.
Generate a competitive landscape PDF
fathom config set export.format pdf
fathom run "Compare Datadog, New Relic and Dynatrace side by side" -o ./landscape/The PDF report renders a side-by-side comparison of the researched competitors.
Export memory facts for graph tooling
fathom memory list --scope all --status active -n 500 > ./memory-export.txtPlain-text export of active facts; adapt the rows to your graph tooling of choice.
Multi-Step Workflow Recipes
Complete playbooks that chain multiple sessions into end-to-end workflows. Each recipe is a sequence of commands designed to be run together or scheduled as a pipeline.
Lead enrichment pipeline (3-step)
# Step 1: Find raw leads
fathom run "Find marketing directors at Series A+ SaaS companies in DACH region" -o ./pipeline/raw
# Step 2: Enrich with LinkedIn and verify emails
fathom run "Enrich the contacts in ./pipeline/raw with LinkedIn profiles and verify all email addresses" -o ./pipeline/enriched
# Step 3: Score and prioritize
fathom run "Score the enriched contacts in ./pipeline/enriched by company size, funding stage, and role seniority. Output top 50 for outreach." -o ./pipeline/readyThis three-step pipeline separates discovery, enrichment, and scoring. Each step can be re-run independently. The intermediate outputs serve as checkpoints for debugging and quality review.
Weekly competitor intelligence digest
# Monday morning: gather all signals
fathom run "Compile a weekly intelligence digest for competitors: Datadog, New Relic, Dynatrace. Include news, blog posts, job postings, social media activity, and any pricing changes." -o ./intel/weekly-$(date +%Y%m%d)Run this as a weekly cron job. Each week's output is date-stamped and stored separately.
Event-driven follow-up research
# When you get a new lead from a webhook:
fathom run "For the company {company_name} that just signed up, find their CTO, VP Engineering, and Head of Product. Research their tech stack, recent hires, and any public statements about {your_product_category}." -o ./follow-up/{company_slug}Designed to be triggered by a CRM webhook or form submission. The agent performs targeted research on the inbound lead's company, giving your sales team context before the first call.
Conference preparation workflow
# 2 weeks before: research attendees
fathom run "Parse the attendee/speaker list from KubeCon EU 2025. Find LinkedIn profiles, current roles, companies, and recent technical blog posts for each person." -o ./events/kccn-eu-2025/attendees
# 1 week before: prioritize
fathom run "From the attendees in ./events/kccn-eu-2025/attendees, identify the top 30 people to meet based on: company relevance to our product, role seniority, and mutual connections." -o ./events/kccn-eu-2025/priorityTwo-phase workflow: broad research first, then focused prioritization. The priority list includes talking points derived from each person's recent activity, making conversations more productive.
Hiring signal detection pipeline
# Daily: scrape new job postings
fathom run "Scrape job postings from Datadog, Snowflake, Databricks, Confluent, and Grafana Labs career pages posted in the last 24 hours. Classify by department, seniority, and technology." --repeat 86400 -o ./hiring/daily
# Weekly: trend analysis
fathom run "Analyze the job postings in ./hiring/daily from the past 7 days. Identify hiring surges by department, new technology adoptions, and geographic expansion patterns." -o ./hiring/weekly-trendsDaily scraping feeds a database of job postings. Weekly analysis detects trends that signal strategic shifts: a surge in ML hiring suggests an AI product, new geo offices suggest expansion.
Supply chain risk monitoring
# Monthly: map the supply chain
fathom run "Map the full supply chain for {product}. Identify all tier-1 and tier-2 suppliers, their geographic locations, financial health, and any recent news about disruptions, sanctions, or regulatory actions." -o ./supply-chain/{product}/monthly-$(date +%Y%m)
# Compare with prior month
fathom run "Compare the supply chain map in ./supply-chain/{product}/monthly-$(date +%Y%m) with the previous month. Highlight any new risks, removed suppliers, or geographic shifts."Monthly cadence balances freshness with cost. The comparison step uses the diff engine to surface only changes, making the risk report actionable rather than repetitive.
Content gap analysis workflow
fathom run "Analyze the top 10 blog posts, whitepapers, and webinars published by our competitors (list them) in the past quarter. For each piece of content, extract the topic, target persona, format, and estimated engagement. Identify content gaps where we have no competing content." -o ./content/gap-analysisThe agent visits each competitor's content hub, classifies content by topic and persona, and cross-references against your content catalog (if provided). The gap report highlights opportunities ranked by estimated traffic potential.
Investor research for fundraising prep
fathom run "Research the top 50 VCs that invest in B2B SaaS Series A in Europe. For each fund, find: investment thesis, portfolio companies in our space, key partners, check size, and recent deals. Identify warm introduction paths through our network." -o ./fundraising/vc-listInvestor research combines Crunchbase data with partner LinkedIn profiles and portfolio analysis. Warm path detection cross-references your team's LinkedIn connections against VC partner networks.
Запустите инструменты
Three ways to interact with Fathom: terminal UI for hands-on work, HTTP server for dashboards and APIs, and MCP for AI-native tool integration.
Терминальный UI
fathom tui — следите за флотом вживую, одобряйте побочные эффекты, просматривайте задачи и память.
HTTP + дашборд
fathom serve — SSE-потоки, API задач и дашборд только для чтения на /dashboard.
MCP для Claude/ZCode
fathom mcp-serve — открывает 63 всегда зарегистрированных инструмента, до 5 CDP-браузерных и до 6 компьютерных при настройке любому MCP-клиенту через stdio.
Full Recipe Index
All recipes at a glance. Click a section link to jump to the full recipe with command and explanation.
Quick Start (4)
OSINT & Lead Generation (8)
Research & Analysis (7)
Memory & Knowledge (6)
Automation & Watch (5)
API & Integrations (6)
Advanced Config (6)
Troubleshooting (9)
Export & Reporting (8)
Multi-Step Workflows (8)
Common Flags Reference
Flags that work across most recipes. Combine them to customize behavior without changing config files.
| Flag | Description | Default |
|---|---|---|
-o <dir> | Output directory for results, contacts DB, and session logs | ./research-output/ |
–profile <name> | Load a named profile (hunter, analyst, validator, or custom) | Default profile |
–repeat <seconds> | Re-run interval for session | 3600 |
–depth <1-5> | Research depth (1-5) | 3 |
–fast | Fast mode with reduced depth | Off |
RUST_LOG=debug | Enable debug logging via environment variable | info |
–approval-gate <tool> | Require approval before executing a specific tool | None |
<session-id> | Optional positional session identifier for resume | Latest interrupted |
–dry-run | Show what would happen without executing side effects | Off |
–confirm | Skip confirmation prompts for destructive operations | Off |
Quick Config Reference
Common configuration commands used across recipes. Run fathom config show to see all options.
Model Configuration
fathom config set agent.role_models.writer "openai/gpt-4o"
fathom config set agent.role_models.researcher "deepseek/deepseek-chat"
fathom config set agent.role_models.verifier "openai/gpt-4o-mini"
fathom config set agent.role_models.default "openai/gpt-4o"Alert Configuration
fathom config set alerts.telegram.bot-token "123456:ABC..."
fathom config set alerts.telegram.chat-id "-1001234567890"
fathom config set alerts.email.to "[email protected]"
fathom config set alerts.webhook.url "https://hooks.slack.com/..."Search Configuration
fathom config showContext & Memory
fathom config set context.context_window 128000
fathom config set context.compact_threshold 0.85Getting Help
Stuck? These commands point you in the right direction.
List all available commands
fathom --helpShows all top-level commands with descriptions. Use –help on any subcommand for detailed flags and examples.
Show current configuration
fathom config showDumps all config values with their sources (default, file, env var, or CLI flag). Useful for debugging unexpected behavior.
Check system health
fathom memory statsShows memory graph statistics and health.
View session logs
RUST_LOG=debug fathom run "..."Enable debug logging to see every tool call, decision, and error with timestamps.
List active sessions
fathom memory listShows all facts, entities, and relationships in the memory graph.
Show version and build info
fathom --versionDisplays the binary version and build info. Useful for bug reports.
Reset to factory defaults
rm ~/.fathom/config.tomlRemove the config file to reset to defaults.
Tips & Best Practices
Hard-won advice from production deployments. These tips help you get better results, avoid common pitfalls, and keep costs under control.
Write specific, structured prompts
# Vague (low quality results):
"Find leads in fintech"
# Specific (high quality results):
"Find CTOs and VP Engineering at B2B fintech
startups in London with 50-200 employees that
raised Series A or B in the past 18 months.
Verify each email via SMTP probe. Include
company size, last funding round, and tech
stack from job postings."Specificity drives quality. Include geography, company size, role, verification method, and enrichment fields. The agent performs better with clear success criteria.
Use -o for reproducibility
# Always specify output directory
fathom run "..." -o ./leads/q1-2025
# Re-run produces deterministic structure
ls ./leads/q1-2025/
# contacts.db session.json sources/ synthesis.mdExplicit output directories make results versionable, comparable, and easy to reference in follow-up sessions. The deterministic structure means scripts can reliably process outputs.
Start shallow, then go deep
# First pass: broad, shallow
fathom run "..." --depth 2 -o ./broad
# Second pass: deep dive on top results
fathom run "Analyze top 20 from ./broad"Shallow depth is faster and cheaper. Use it to identify the most promising targets, then invest deep research only on the best candidates. This two-pass approach cuts costs by 60-80%.
Chain sessions with memory
# Session 1: research
fathom run "..." -o ./research
# Session 2: uses memory from session 1
fathom memory distill --session latest
fathom run "Using prior research, ..." -o ./follow-upDistilling session facts into memory makes them available to future sessions. The memory graph connects entities across sessions, so the second session benefits from all prior context.
Docker & Deployment Recipes
Run Fathom in production. Docker, systemd, reverse proxies, health checks, backups, and scaling — everything you need for a reliable deployment.
Run the HTTP server with Docker
docker run -d --name fathom \
-v ./data:/data \
-v ~/.fathom:/home/researcher/.fathom \
-e FATHOM_API_KEYS=$FATHOM_API_KEYS \
-p 8080:8080 \
fathom:latest serve --port 8080Mount persistent state and expose the authenticated HTTP control plane. Configure the LLM provider in the mounted config file.
Deploy to a VPS with systemd
# Create /etc/systemd/system/fathom.service from your deployment settings
# ExecStart=/usr/local/bin/fathom serve --port 8080
# Restart=on-failure
# Set FATHOM_API_KEYS in the unit environment
sudo systemctl daemon-reload
sudo systemctl enable --now fathomThe repository does not ship a unit file. Create one for your host, then use systemd to start the HTTP server on boot and restart it after failures.
Run behind Nginx reverse proxy
# /etc/nginx/sites-available/fathom
# server {
# listen 443 ssl http2;
# server_name research.example.com;
# ssl_certificate /etc/letsencrypt/live/research.example.com/fullchain.pem;
# ssl_certificate_key /etc/letsencrypt/live/research.example.com/privkey.pem;
# location / {
# proxy_pass http://127.0.0.1:8080;
# proxy_set_header Host $host;
# proxy_set_header X-Real-IP $remote_addr;
# proxy_buffering off;
# proxy_cache off;
# }
# }Nginx handles TLS termination and proxies to the local Fathom server. Proxy buffering must be disabled for SSE streams to work. Use certbot for free Let's Encrypt certificates.
Set up health check monitoring
# Add to your monitoring system (UptimeRobot, Healthchecks.io, etc.)
curl -f http://localhost:8080/health || exit 1
# Prometheus scrape config
# scrape_configs:
# - job_name: fathom
# static_configs:
# - targets: ['localhost:8080']
# metrics_path: /metricsThe /health endpoint returns HTTP 200 when all components are healthy, 503 when degraded. The /metrics endpoint exposes Prometheus-compatible counters and histograms. Set up alerts on session_failure_total and agent_stall_total.
Backup and restore data
cp -r ~/.fathom ~/.fathom.bak
# restore:
cp -r ~/.fathom.bak ~/.fathomAlways backup your data directory before upgrades or destructive commands like memory nuke.
Run in a tmux session for persistence
tmux new-session -d -s research "fathom mcp-serve"
tmux attach -t research
# Or run a long research task
tmux new-session -d -s research "fathom run 'Deep analysis of...' -o ./analysis"
tmux lstmux keeps the session alive if your SSH connection drops. Reattach with tmux attach -t research. Useful for long-running watch mode sessions or batch jobs that take hours.
Scale with multiple instances on different ports
fathom mcp-serve &Use Nginx upstream for load balancing.
Configure for CI/CD pipeline
# .github/workflows/research.yml
# name: Weekly Research
# on:
# schedule:
# - cron: '0 9 * * 1'
# jobs:
# research:
# runs-on: ubuntu-latest
# steps:
# - uses: actions/checkout@v4
# - name: Build Fathom
# run: cargo build --release
# - name: Run research
# env:
# FATHOM_API_KEYS: ${{ secrets.FATHOM_API_KEYS }}
# OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
# run: fathom run "weekly tasks" -o ./results/
# - name: Upload results
# uses: actions/upload-artifact@v4
# with:
# name: research-results
# path: ./results/GitHub Actions runs the batch on a weekly schedule. Secrets store API keys securely. Results are uploaded as artifacts for download. Add a notification step (Slack webhook) to alert the team when the batch completes.
Docker deployment
The repository does not ship a Docker Compose file. Build the image from the checkout and run it directly, or provide an operator-owned Compose definition for your environment.
Environment Variables
All environment variables that Fathom recognizes. Set these in your shell, .env file, or Docker container. CLI flags and config values take precedence over environment variables.
| Variable | Description | Example |
|---|---|---|
FATHOM_API_KEYS | Primary API key for the Fathom service | key-abc123… |
OPENAI_API_KEY | OpenAI API key for GPT-4o and GPT-4o-mini models | sk-proj-… |
DEEPSEEK_API_KEY | DeepSeek API key for the default OpenAI-compatible endpoint | sk-… |
GITHUB_TOKEN | GitHub personal access token for higher API rate limits | ghp_… |
GOOGLE_CSE_KEY | Google Custom Search Engine API key | AIza… |
GOOGLE_CSE_ID | Google Custom Search Engine ID | a1b2c3d4e5… |
PR_OUTPUT_DIR | Override the configured output directory | /data/fathom |
PR_CONFIG | Override the config.toml path | /etc/fathom/config.toml |
PR_MEMORY_DB | Override the memory SQLite database path | /data/fathom/memory.db |
PARALLEL_CDP_ENDPOINT | Chrome DevTools Protocol endpoint for browser tools | ws://127.0.0.1:9222 |
FATHOM_RATE_LIMIT | HTTP server rate limit per client (requests per minute) | 120 |
HTTP_PROXY | HTTP proxy for outbound requests | http://proxy:8080 |
HTTPS_PROXY | HTTPS proxy for outbound requests | http://proxy:8080 |
NO_PROXY | Comma-separated list of hosts to bypass proxy | localhost,127.0.0.1 |
TELEGRAM_BOT_TOKEN | Telegram bot token (alternative to config) | 123456:ABC… |
TELEGRAM_CHAT_ID | Telegram chat ID for alerts (alternative to config) | -1001234567890 |
WEBHOOK_URL | Default webhook URL for session events | https://hooks.slack.com/… |
CRM_PROVIDER | CRM provider for contacts push (amocrm, bitrix24, hubspot) | hubspot |
CRM_API_KEY | API key for the configured CRM provider | pat-na1-… |
Example .env File
Copy this template and fill in your keys. The agent loads .env from the current directory automatically.
# Required
FATHOM_API_KEYS=key-your_api_key_here
# Model providers (at least one required)
OPENAI_API_KEY=sk-proj-your_openai_key
DEEPSEEK_API_KEY=sk-your_deepseek_key
# Optional: higher rate limits for source scraping
GITHUB_TOKEN=ghp_your_github_token
GOOGLE_CSE_KEY=AIza_your_google_key
GOOGLE_CSE_ID=your_search_engine_id
# Optional: alerting
TELEGRAM_BOT_TOKEN=123456:ABC-your_bot_token
TELEGRAM_CHAT_ID=-1001234567890
WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../xxx
# Optional: CRM integration
CRM_PROVIDER=hubspot
CRM_API_KEY=pat-na1-your_hubspot_key
# Optional: local data paths
PR_OUTPUT_DIR=./research-output
PR_MEMORY_DB=~/.fathom/memory.db
# Optional: logging
RUST_LOG=info