Named after the falcon known for spotting prey from remarkable heights — built to spot opportunity and risk before anyone else does.
Kestrel is a self-hosted, agentic AI system specialized in strategy, market research, and business intelligence — built on Hermes Agent and connected to any OpenAI-compatible model gateway of your choice.
It exists to answer one question before any work begins: "Are we solving the right problem, in the right way?" It researches technology landscapes, evaluates competitors, assesses opportunities, and produces executive-level recommendations — reachable from Telegram, Discord, WhatsApp, or Slack.
| Area | What It Does |
|---|---|
| Technology Intelligence | Monitors emerging tech, compares frameworks, recommends adoption |
| Business Intelligence | Market analysis, business model evaluation, pricing strategy |
| Competitive Intelligence | Competitor profiling, SWOT analysis, market positioning |
| Opportunity Assessment | Feasibility studies, priority matrices, go/no-go recommendations |
| Executive Advisory | Strategic briefs, roadmaps, decision memos |
| Category | Options |
|---|---|
| Messaging | Telegram, Discord, WhatsApp, Slack |
| Model Providers | Any OpenAI-compatible endpoint — hosted, local, or routed |
| Search | DuckDuckGo (free), Brave Search, Exa, Tavily |
| Documents | Word, Excel, PowerPoint, PDF (for reports and briefs) |
| Memory | Persistent memory across sessions |
| Skills | Community skills via skills.sh — see below |
Kestrel doesn't lock you into one paid API. Point MODEL_GATEWAY_BASE_URL at a routing layer (such as 9Router or similar) that sits between the agent and your actual model providers.
This unlocks:
- Combo/fallback chains — a fast model first, a stronger one as fallback if it fails or rate-limits
- Mix free and paid tiers — route through generous free tiers (e.g. Google Gemini API's free tier, Groq's free tier) alongside paid ones
- Provider-agnostic — swap providers later without touching this agent's code
Configure your router's combo logic on the router's own side — this repository just calls whatever OpenAI-compatible endpoint you point it at.
Kestrel can use community-built Agent Skills — reusable capabilities maintained by an open registry.
npx skills find "competitive analysis"
npx skills add <owner>/<repo>/<skill-name>
npx skills listPicked specifically for market research, competitive analysis, and executive reporting — not generic starters:
# Research & discovery
npx skills add vercel-labs/skills/find-skills
npx skills add mattpocock/skills/research
npx skills add mattpocock/skills/diagnose
# Competitive & market intelligence
npx skills add coreyhaines31/marketingskills/seo-audit
npx skills add coreyhaines31/marketingskills/site-architecture
npx skills add coreyhaines31/marketingskills/marketing-psychology
npx skills add coreyhaines31/marketingskills/programmatic-seo
npx skills add coreyhaines31/marketingskills/ai-seo
# Executive output & documentation
npx skills add mattpocock/skills/to-prd
npx skills add mattpocock/skills/to-spec
npx skills add mattpocock/skills/edit-article
npx skills add anthropics/skills/pdf
npx skills add anthropics/skills/pptx
# Web research / scraping support
npx skills add scrapegraphai/just-scrape/just-scrape
npx skills add firecrawl/cli/firecrawl
⚠️ Skill names and availability change on the community registry. Always confirm the exact package withnpx skills find "<topic>"or by browsing skills.sh directly before installing.
If you already have skills installed for other tools (Claude Code, OpenCode, Cursor, etc.) sitting somewhere like C:\Users\<you>\.agents\skills, Kestrel can read them too — without mounting or modifying your C: drive.
Approach: copy the skills folder to D:\ or E:\ first, then mount only that copy into the container as read-only.
Windows (PowerShell):
Copy-Item -Recurse "C:\Users\<you>\.agents\skills" "E:\Kestrel-skills"
docker run -d `
--name kestrel `
--restart unless-stopped `
-v ${PWD}:/opt/data `
-v E:\Kestrel-skills:/opt/access/skills:ro `
-p 8642:8642 `
kestrel gateway runmacOS/Linux:
cp -r ~/.agents/skills /path/on/external-or-secondary-drive/kestrel-skills
docker run -d \
--name kestrel \
--restart unless-stopped \
-v "$(pwd)/data:/opt/data" \
-v /path/on/external-or-secondary-drive/kestrel-skills:/opt/access/skills:ro \
-p 8642:8642 \
kestrel gateway runThe :ro flag makes it read-only. C:\ is never referenced in the mount, so the container never touches your system drive.
Installed skills run with the full permissions of the agent — filesystem access, API keys, credentials, shell execution. Prefer well-known maintainers, read a skill's source before installing, and keep the read-only mount pattern above for any pre-existing skill folders.
graph TB
User[Telegram / Discord / WhatsApp / Slack] -->|Message| Gateway[Kestrel<br/>Docker Container]
Gateway -->|OpenAI-compatible API| Router[Model Gateway<br/>e.g. 9Router or similar]
Router -->|Route| M1[Gemini API - free tier]
Router -->|Route| M2[Other providers]
Gateway --> Memory[(Persistent Memory)]
Gateway --> Docs[Document Tools<br/>docx/xlsx/pptx/pdf]
Gateway --> Search[Web Search]
Gateway --> SkillsFolder[(Skills - read-only mount<br/>D:/ or E:/, never C:/)]
style Gateway fill:#6366f1,color:#fff
style Router fill:#f97316,color:#fff
style Memory fill:#10b981,color:#fff
- Docker installed and running
- A model gateway reachable via an OpenAI-compatible endpoint
- A bot token for at least one messaging platform
git clone https://github.com/Maventlabs/Kestrel.git
cd Kestrel
cp .env.example .env
nano .env
docker build -t kestrel .
docker run --rm -it \
-v "$(pwd)/data:/opt/data" \
kestrel setup
docker run -d \
--name kestrel \
--restart unless-stopped \
-v "$(pwd)/data:/opt/data" \
-p 8642:8642 \
kestrel gateway runOn Linux, if your model gateway runs natively on the host, add
--add-host=host.docker.internal:host-gateway.
git clone https://github.com/Maventlabs/Kestrel.git
cd Kestrel
Copy-Item .env.example .env
notepad .env
docker build -t kestrel .
docker run --rm -it `
-v ${PWD}:/opt/data `
kestrel setup
docker run -d `
--name kestrel `
--restart unless-stopped `
-v ${PWD}:/opt/data `
-p 8642:8642 `
kestrel gateway runssh user@your-vps-ip
git clone https://github.com/Maventlabs/Kestrel.git
cd Kestrel
# ... same steps as Linux deployment aboveMinimum recommended specs: 1 vCPU, 1–2GB RAM.
docker compose up -dDuring setup, choose Custom endpoint when prompted for a model provider, then supply:
- Base URL — your gateway's OpenAI-compatible endpoint
- API Key — your gateway's key
- Model ID — the exact model or combo name your gateway expects (see
MODEL_IDin.env.example— required, not optional)
SOUL.md defines the agent's role and communication style, scoped purely to Strategy & Business Intelligence. To personalize:
- Add a section about yourself
- Optionally add a Voice & Persona section for a distinct personality
- Fill in your infrastructure details
- Personal-by-default — one trusted operator boundary
- Never commit
.env,data/, or any credentials - Skills run with full agent permissions — see Skills Security Warning above
- Mounted directories should stay off
C:\/system drives
.
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .env # NEVER commit
├── .gitignore
├── SOUL.md
├── data/ # NEVER commit
├── LICENSE
├── CHANGELOG.md
├── CONTRIBUTING.md
└── README.md
Container can't reach your model gateway
Use host.docker.internal instead of localhost on Windows/macOS. On Linux, add --add-host=host.docker.internal:host-gateway.
Skill install fails or behaves unexpectedly
Run npx skills list to confirm what's installed, and check the skill's SKILL.md for its own requirements.
See CONTRIBUTING.md.
MIT License. Hermes Agent itself is a separate project with its own license.
See CHANGELOG.md.