prowlrbot 1.0.0

ProwlrBot — Always watching. Always ready. An autonomous AI agent platform for monitoring, automation, and multi-channel communication.

ProwlrBot

Always watching. Always ready.
Your AI agent. Your machine. Your rules.

Quick Start • Screenshots • Docs • Marketplace • ROAR Protocol • Sponsor

---

ProwlrBot is a self-hosted AI agent platform that runs on your machine, connects to every channel you use, and keeps working while you sleep.

It monitors websites for changes. It runs scheduled tasks. It answers your team on Discord, Telegram, Slack, and WhatsApp at the same time. It coordinates multiple AI agents in a War Room so they don't step on each other. It does all of this with your API keys, your models, your data — nothing leaves your network unless you want it to.

No subscription. No vendor lock-in. Install and own it forever.

pip install prowlrbot && prowlr init --defaults && prowlr app

---

What It Looks Like

Mission Control Dashboard Real-time overview of your agent, channels, and system health	Chat Interface Talk to your agent with full tool use, code execution, and file handling
Skills Marketplace Browse, install, and publish skills — PDF processing, email, monitoring, and more
Web Monitoring Watch websites and APIs for changes — get alerted when something moves	MCP Server Integration Connect any MCP server — tools appear instantly with hot-reload
Channel Management Discord, Telegram, Slack, WhatsApp, DingTalk, Feishu, iMessage — all at once	Team Builder Design multi-agent teams with specialized roles and capabilities

More screenshots

Skills Manager	Agent Workspace
Scheduled Tasks	Theme Customization
Hardware Advisor

---

Why ProwlrBot?

There are a lot of AI chatbots. ProwlrBot is not a chatbot. It's an agent that acts.

The old way	With ProwlrBot
Check 10 tabs manually every morning	Agent monitors all of them, pings you only when something changes
Forget to follow up on something	Schedule it once — the agent handles it at 9am every day
Three Claude terminals stepping on each other	War Room coordinates them — file locks, shared task board, zero conflicts
Paying $50/mo for a tool that phones home	Self-hosted, model-agnostic, free forever
Building separate bots for Discord + Telegram + Slack	One agent, all channels, same brain

Core Principles

• Your data stays yours. API keys are encrypted locally. Chat history lives on your machine. Run entirely on local models with Ollama — no API key, no data leaving your network.
• It speaks where you already are. One agent, 8+ channels. Discord, Telegram, Slack, WhatsApp, DingTalk, Feishu, iMessage, Console. Custom channels too.
• It grows with you. Skill marketplace for adding capabilities. ROAR Protocol for agent-to-agent communication across machines and organizations.

---

Get Started in 60 Seconds

# 1. Install
pip install prowlrbot

# 2. Initialize (auto-detects local models)
prowlr init --defaults

# 3. Set an API key (optional — skip if using Ollama)
prowlr env set OPENAI_API_KEY sk-your-key

# 4. Launch
prowlr app

Open http://localhost:8088 — your agent is live.

No API key? ProwlrBot auto-detects Ollama. Just prowlr init --defaults && prowlr app.

Install from source (development)

git clone https://github.com/ProwlrBot/prowlrbot.git
cd prowlrbot
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
prowlr init --defaults
prowlr app

Docker

docker pull ghcr.io/prowlrbot/prowlrbot:latest
docker run -p 8088:8088 -v ~/.prowlrbot:/root/.prowlrbot ghcr.io/prowlrbot/prowlrbot:latest

Desktop App (macOS / Windows / Linux)

Download from GitHub Releases or build yourself:

# macOS (.app + DMG)
bash packaging/build_macos.sh

# Windows (.exe)
powershell -File packaging/build_windows.ps1

# Linux (binary + AppImage)
bash packaging/build_linux.sh --appimage

System tray app with one-click launch. Full guide →

WSL notes

• Clone to /home/user/prowlrbot, not /mnt/c/...
• Create venv inside the project: python3 -m venv .venv
• See Troubleshooting Guide for WSL-specific issues

---

Architecture

                    YOU
                     │
          ┌──────────┼──────────┐
          ▼          ▼          ▼
      Discord    Telegram    Slack       + 6 more channels
          │          │          │
          └──────────┼──────────┘
                     ▼
             ChannelManager              queue + debounce (4 workers/channel)
                     │
                     ▼
              AgentRunner                session management
                     │
                     ▼
           ProwlrBotAgent (ReAct)        reasoning loop
            ┌────┬────┬────┬────┐
            ▼    ▼    ▼    ▼    ▼
         Tools Skills MCP Memory ROAR    capabilities
            │    │    │    │    │
            └────┼────┼────┼────┘
                 ▼    ▼    ▼
         ┌───────────────────────┐
         │     Smart Router      │       cost × w₁ + speed × w₂ + avail × w₃
         ├───────────────────────┤
         │ OpenAI  │ Anthropic   │
         │ Groq    │ Z.ai        │
         │ Ollama  │ llama.cpp   │
         │ MLX     │ Azure       │
         └───────────────────────┘
                     │
                     ▼
              ChatManager                persistence (chats + sessions)

Provider detection flow:

Environment Scan → ProviderDetector (env vars) → HealthChecker (async probes)
→ SmartRouter (score = w_cost × cost + w_perf × perf + w_avail × avail)
→ Selected Provider → FallbackChain on failure

---

Features

Multi-Agent War Room

The killer feature: multiple AI agents coordinate in real-time without stepping on each other.

╔══════════════════════════════════════════════════════════════╗
║                      MISSION BOARD                          ║
╠════╦══════════════════════╦═══════════╦══════════════════════╣
║ ID ║ Task                 ║ Agent     ║ Status               ║
╠════╬══════════════════════╬═══════════╬══════════════════════╣
║  1 ║ Build auth API       ║ backend   ║ In Progress          ║
║  2 ║ Login page           ║ frontend  ║ In Progress          ║
║  3 ║ Write auth tests     ║ tester    ║ Waiting (locked)     ║
║  4 ║ API documentation    ║ --        ║ Available            ║
╚════╩══════════════════════╩═══════════╩══════════════════════╝

13 coordination tools — check_mission_board, claim_task, lock_file, share_finding, and more.

Quick War Room setup

# 1. Start the hub
cd prowlrbot && PYTHONPATH=src python3 -m prowlrbot.hub.bridge

# 2. In your project's .mcp.json:
{
  "mcpServers": {
    "prowlr-hub": {
      "command": "python3",
      "args": ["-m", "prowlrbot.hub"],
      "cwd": "/path/to/prowlrbot",
      "env": {
        "PYTHONPATH": "/path/to/prowlrbot/src",
        "PROWLR_AGENT_NAME": "frontend",
        "PROWLR_CAPABILITIES": "react,typescript,css"
      }
    }
  }
}

# 3. Restart Claude Code, then:
# "Call check_mission_board and get_agents to see the War Room."

Cross-machine support via HTTP bridge + Tailscale/Cloudflare. Full guide →

---

Smart Model Router

Automatically picks the best provider based on scoring:

score = cost × w₁ + speed × w₂ + availability × w₃

Provider	How to Enable	Cost
OpenAI	OPENAI_API_KEY	$$
Anthropic	ANTHROPIC_API_KEY	$$
Groq	GROQ_API_KEY	$
Z.ai	ZAI_API_KEY	$$
Ollama	Auto-detected locally	Free
llama.cpp	pip install 'prowlrbot[llamacpp]'	Free
MLX	pip install 'prowlrbot[mlx]' (Apple Silicon)	Free

Falls back automatically if a provider fails. Zero config needed — just set the API key and ProwlrBot finds it.

---

9+ Communication Channels

Discord Built-in	Telegram Built-in	Slack Setup guide	WhatsApp Setup guide
DingTalk Built-in	Feishu/Lark Built-in	QQ Built-in	iMessage macOS only
Console Default	Custom channels via ~/.prowlrbot/custom_channels/

One agent brain, all channels simultaneously. Build custom channels for anything else. Channel guide →

---

Skills Marketplace

Browse, install, and publish skills that extend your agent:

prowlr market search "monitor"       # Find skills
prowlr market install site-monitor   # Install one
prowlr market seed                   # Load all official listings + bundles

11 official listings — morning briefing, smart reminders, site monitor, competitor watch, invoice chaser, and more. 6 curated bundles — Security Starter, Full-Stack Dev, Data & Analytics, Document Pro, Daily Essentials, Business Ops.

Submit your own skills through the console UI or CLI. Marketplace guide →

---

Web Monitoring & Cron Jobs

# Monitor a website for changes
prowlr monitor add https://example.com/pricing --interval 1h

# Schedule an autonomous agent task
prowlr cron add "Check email and summarize" --schedule "0 9 * * *"
prowlr cron add "Monitor competitors" --interval 30m

---

ROAR Protocol

One protocol. Any agent. ProwlrBot speaks ROAR — the open agent communication protocol that bridges MCP, A2A, and ACP.

Layer 5: Stream     Real-time events (SSE, WebSocket)
Layer 4: Exchange   ROARMessage — 7 intent types, HMAC signing
Layer 3: Connect    HTTP | WebSocket | stdio | gRPC
Layer 2: Discovery  Hub + Cache + SQLite directory
Layer 1: Identity   W3C DIDs (did:roar, did:key, did:web)

# Check any ROAR agent
curl -s https://app.prowlrbot.com/roar/health
curl -s https://app.prowlrbot.com/roar/card | jq .

ROAR examples

# Send a task to another agent
from prowlrbot.protocols.sdk import AgentIdentity, MessageIntent
from prowlrbot.protocols.sdk.client import ROARClient

identity = AgentIdentity(display_name="my-agent", capabilities=["code-review"])
client = ROARClient(identity, signing_secret=os.environ["ROAR_SHARED_SECRET"])

response = await client.send_remote(
    to_agent_id="did:roar:agent:reviewer-abc123",
    intent=MessageIntent.DELEGATE,
    content={"task": "Review main.py"},
)

Three runnable examples in examples/roar/:

1. Basic message exchange — sign, send, verify
2. MCP bridge — translate MCP tool calls through ROAR
3. Multi-agent delegation — coordinator discovers and delegates to specialized agents

Live Demo → • ROAR Spec → • Usage Guide → • PyPI Package →

---

v1.0.0 — What's New

35 features shipped in v1.0.0

Security & Trust

• Fine-grained tool permissions with command blocklist and file sandboxing
• Agent safety guardrails — loop detection, token budgets, exponential backoff
• Cost dashboard with real-time tracking, budget limits, and model fallback
• Automated security audit (GET /api/health/security-audit) covering OWASP Top 10
• 23 security vulnerabilities found and fixed across the codebase

Intelligence

• Vector-based semantic memory search with local ONNX embeddings
• RAG pipeline — ingest PDF, DOCX, TXT, code files with intelligent chunking
• Agent templates — 11 pre-built personas (DevOps, SRE, Research, Community Manager, etc.)
• Memory visualization API — timeline, stats, semantic search, compaction

Automation

• Webhook gateway — receive triggers from GitHub, Stripe, or any HTTP source
• Advanced web monitor — visual diff engine with smart alert filtering
• Huginn & n8n migration toolkit — prowlr import-from CLI

Infrastructure

• Docker Compose one-click production stack
• Desktop app packaging (macOS DMG, Windows EXE, Linux AppImage)
• Plugin & middleware extension system
• A2A protocol client for cross-agent task delegation

Console UI

• Mission Control redesign with StatusBar, CommandPalette (Ctrl+K), ContextPanel
• Cost dashboard, trace viewer, health dashboard pages
• Responsive mobile PWA with bottom tab bar
• Onboarding setup wizard for first-run experience

AgentVerse — standalone app

• Gamified agent coordination — zones, avatars, XP, guilds, arena, trades
• Real-time WebSocket updates with prowlr-office design system
• Connects to any ProwlrBot instance via PROWLRBOT_URL

Full changelog →

---

Security

ProwlrBot is built with a security-first posture:

• JWT authentication — all API endpoints require a signed JWT. Tokens are issued on login and validated on every request via FastAPI middleware.
• RBAC — four roles enforced at the route level: admin (full access), operator (run agents, manage channels/cron), viewer (read-only), agent (machine-to-machine, limited to task and finding endpoints).
• CSRF protection — double-submit cookie pattern applied to all state-mutating endpoints.
• Rate limiting — per-IP and per-user limits on the API to prevent abuse.
• Secret isolation — API keys and tokens are stored in ~/.prowlrbot.secret/envs.json (mode 0o600), never in the main config file.
• Bandit scan — automated static analysis runs in CI. Current result: 0 high-severity issues.
• Security audit endpoint — GET /api/health/security-audit checks OWASP Top 10 coverage at runtime.

---

MCP Integration

Connect any Model Context Protocol server — tools appear instantly with hot-reload:

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
      }
    }
  }
}

---

Local Models (No Cloud Required)

Run everything on your machine. No API keys. No data leaving your computer.

Backend	Best For	Install
Ollama	Cross-platform, easiest	ollama.ai
llama.cpp	GGUF models, CPU/GPU	pip install 'prowlrbot[llamacpp]'
MLX	Apple Silicon (M1-M4)	pip install 'prowlrbot[mlx]'

ProwlrBot auto-detects Ollama on startup. No configuration needed.

---

Desktop App

Native system tray app for macOS, Windows, and Linux. One click to launch, no terminal required.

# Build for your platform
bash packaging/build_macos.sh      # .app + DMG
powershell packaging/build_windows.ps1  # .exe
bash packaging/build_linux.sh --appimage  # AppImage

Purple circle = idle. Green = active. Red = error. Build guide →

---

Project Structure

prowlrbot/
├── src/prowlrbot/
│   ├── agents/              # ReAct agent, tools, skills, memory
│   ├── app/                 # FastAPI app, channels, cron, MCP, routers
│   ├── cli/                 # Click CLI (`prowlr` command)
│   ├── config/              # Pydantic models + hot-reload
│   ├── providers/           # Model registry, detector, smart router
│   ├── protocols/           # ROAR protocol SDK + A2A server + client
│   ├── marketplace/         # Skill marketplace store + seed data
│   ├── monitor/             # Web/API change detection + visual diff
│   ├── rag/                 # RAG pipeline — ingest, chunk, retrieve
│   ├── webhooks/            # Webhook gateway — triggers + actions
│   ├── agentverse/          # AgentVerse world state + event hooks
│   ├── security/            # Audit reports + middleware
│   ├── desktop/             # System tray launcher (PyInstaller)
│   ├── migrate/             # Huginn + n8n import tools
│   ├── backup/              # Conversation backup engine
│   ├── workflows/           # Visual automation engine
│   ├── plugins/             # Plugin lifecycle + middleware
│   ├── hub/                 # ProwlrHub war room (MCP server)
│   └── envs/                # Encrypted secret store
├── console/                 # React 18 + Vite + Ant Design dashboard
├── packages/roar-sdk-ts/    # TypeScript ROAR SDK
├── marketplace-listings/    # 11 official skill listings
├── examples/roar/           # ROAR protocol examples
├── packaging/               # Desktop build scripts (macOS/Win/Linux)
├── swarm/                   # Cross-machine Redis execution
├── plugins/                 # Claude Code plugins
├── docs/                    # Documentation hub
│   ├── guides/              # Setup, channels, desktop, marketplace
│   ├── protocols/           # ROAR spec + layer docs
│   └── blog/                # Project blog
└── website/                 # GitHub Pages docs site

---

Documentation

Guide	What You'll Learn
Channel Setup	Connect Discord, Telegram, DingTalk, Feishu, iMessage, QQ
Slack Setup	Custom channel with Slack Bolt + Socket Mode
WhatsApp Setup	WhatsApp Business Cloud API + webhooks
Provider Config	OpenAI, Anthropic, Groq, Ollama, local models
Skills Guide	Enable, create, and publish skills
MCP Setup	Connect filesystem, GitHub, Postgres MCP servers
Marketplace	Browse, install, publish, credits system
Monitoring	Watch websites and APIs for changes
Cron Jobs	Schedule autonomous agent tasks
Desktop Build	Build DMG/EXE/AppImage desktop app
Deployment	Docker, Fly.io, systemd, nginx
ROAR Protocol	Agent communication spec — identity, discovery, streaming
Cross-Network	Connect agents across machines
Memory System	Tiered memory, vector search, RAG
CLI Reference	Every command, every flag
Troubleshooting	WSL, pip, ports, MCP, console fixes

Full docs index →

---

Ecosystem

Project	Description
ProwlrBot	Core agent platform (you are here)
ROAR Protocol	Agent communication standard — pip install roar-protocol
Marketplace	Skills & agents marketplace
AgentVerse	Gamified agent world — zones, avatars, XP, guilds, arena
prowlr-office	Collaborative workspace for humans + AI agents (coming soon)
Docs	Centralized documentation

---

Testing

The test suite uses pytest with pytest-asyncio (asyncio_mode = "auto"). 1,085 tests currently pass.

pytest                          # full suite
pytest -m "not slow"           # skip integration/slow tests
pytest tests/test_react_agent_tool_choice.py  # single file

---

Contributing

We welcome contributions! See CONTRIBUTING.md for commit conventions and PR guidelines.

Good first ways to get involved:

• Star the repo — helps more people find the project
• Open an issue — bugs, questions, ideas
• Start a discussion — share your setup, ask how something works
• Build a skill — publish it to the marketplace
• Tell someone — word of mouth is the fastest way to grow

---

Support the Project

ProwlrBot is free, open source, and will stay that way. If it saves you time, consider sponsoring.

     

---

License

ProwlrBot is open source under the Apache 2.0 License.

---

ProwlrBot — Always watching. Always ready.
Built by kdairatchi

Docs • Blog • Discussions • Issues • Marketplace • Contribute • Sponsor