<img src="paw.png" alt="PocketPaw" width="100"> <h1 align="center">🐾 PocketPaw</h1> An AI agent that runs on your machine, not someone else's. <a href="https://pypi.org/project/pocketpaw/"><img src="https://img.shields.io/pypi/v/pocketpaw.svg" alt="PyPI version"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a> <a href="https://pypi.org/project/pocketpaw/"><img src="https://img.shields.io/pypi/dm/pocketpaw.svg" alt="Downloads"></a> <a href="https://github.com/pocketpaw/pocketpaw/stargazers"><img src="https://img.shields.io/github/stars/pocketpaw/pocketpaw?style=social" alt="GitHub Stars"></a> <a href="https://github.com/pocketpaw/pocketpaw/releases/download/client-v0.1.3/PocketPaw_0.1.3_x64-setup.exe"><img src="https://img.shields.io/badge/Windows-Download_.exe-0078D4?style=for-the-badge&logo=windows&logoColor=white" alt="Download for Windows"></a> <a href="https://github.com/pocketpaw/pocketpaw/releases/download/client-v0.1.3/PocketPaw_0.1.3_aarch64.dmg"><img src="https://img.shields.io/badge/macOS-Download_.dmg-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Download for macOS"></a> <a href="https://github.com/pocketpaw/pocketpaw/releases/download/client-v0.1.3/PocketPaw_0.1.3_amd64.AppImage"><img src="https://img.shields.io/badge/Linux-Download_.AppImage-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Download for Linux"></a> Self-hosted AI agent with a native desktop app and web dashboard. Talks to you over Discord, Slack, WhatsApp, Telegram, or the browser. No subscription. No cloud lock-in. Your data stays on your machine.

⚠️ Beta: This project is under active development. Expect breaking changes between versions.

Quick Start

Desktop App (Recommended)

Download the native desktop app. It bundles the backend installer and provides a full-featured UI with system tray, global shortcuts, side panel, and multi-window support.

| Platform | Download | | --- | --- | | Windows | PocketPaw_0.1.3_x64-setup.exe | | macOS (Apple Silicon) | PocketPaw_0.1.3_aarch64.dmg | | macOS (Intel) | PocketPaw_0.1.3_x64.dmg | | Linux (.deb) | PocketPaw_0.1.3_amd64.deb | | Linux (.AppImage) | PocketPaw_0.1.3_amd64.AppImage |

Install via Terminal

<details open> <summary>macOS / Linux</summary>

Prerequisites:

Python 3.11 or higher (download here)
pip package manager (included with Python)

Quick install:

pip install pocketpaw && pocketpaw

Recommended install (with virtual environment):

# 1. Verify Python version (must be 3.11+)
python3 --version

# 2. Upgrade pip to latest version
python3 -m pip install --upgrade pip

# 3. Create and activate virtual environment (optional but recommended)
python3 -m venv pocketpaw-env
source pocketpaw-env/bin/activate

# 4. Install PocketPaw
pip install pocketpaw

# 5. Run PocketPaw
pocketpaw

Or use the automated install script:

curl -fsSL https://pocketpaw.xyz/install.sh | sh

</details> <details> <summary>Windows (PowerShell)</summary>

Windows Installation (Step-by-Step)

Prerequisites:

Python 3.11 or higher — Download Python. During setup, check "Add Python to PATH".
pip (included with Python)

Option A — Automated installer (recommended for beginners):

powershell -NoExit -Command "iwr -useb https://pocketpaw.xyz/install.ps1 | iex"

Option B — Manual install:

Open PowerShell and verify Python version (must be 3.11+):
```
python --version
```
Upgrade pip:
```
python -m pip install --upgrade pip
```
(Optional but recommended) Create and activate a virtual environment:
```
python -m venv pocketpaw-env
.\pocketpaw-env\Scripts\Activate.ps1
```
Install PocketPaw:
```
pip install pocketpaw
```
Verify the installation by running:
```
pocketpaw --help
```
Or start the dashboard:
```
pocketpaw
```

Windows Troubleshooting

If you installed PocketPaw with pip install pocketpaw and the pocketpaw command is not recognized:

'pocketpaw' is not recognized as an internal or external command

This usually means your Python Scripts directory is not on your PATH. By default it is at:

C:\Users\<your-username>\AppData\Local\Python\Python3.XX\Scripts

Find your exact Scripts path:

python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

How to fix:

Open Start → Search "Environment Variables"
Click "Edit the system environment variables"
Click "Environment Variables"
Under User variables → Select Path → Click Edit
Add the Scripts directory path
Restart your terminal

Alternatively, run PocketPaw without adding Scripts to PATH:

python -m pocketpaw

[!TIP] First Run: After opening the dashboard, the system health may show UNHEALTHY. This is expected until at least one model provider is configured. The app itself is running correctly; only AI features are disabled. See Setting up your first API key, or use Ollama for free local inference.

Note: Some features (browser automation, shell tools) work best under WSL2. Native Windows support covers the web dashboard and all LLM chat features.

</details> <details> <summary>Other methods</summary>

pipx install pocketpaw && pocketpaw    # Isolated install
uvx pocketpaw                           # Run without installing

# From source
git clone https://github.com/pocketpaw/pocketpaw.git
cd pocketpaw && uv run pocketpaw

</details> <details> <summary>Docker</summary>

git clone https://github.com/pocketpaw/pocketpaw.git && cd pocketpaw
cp .env.example .env
docker compose up -d

Dashboard at http://localhost:8888. Get the access token:

docker exec pocketpaw cat /home/pocketpaw/.pocketpaw/access_token

Agent-created files appear in ./workspace/ on the host. Optional profiles: --profile ollama (local LLMs), --profile qdrant (vector memory). Using Ollama on the host? Set POCKETPAW_OLLAMA_HOST=http://host.docker.internal:11434 in .env.

</details>

The web dashboard opens at http://localhost:8888. From there you can connect Discord, Slack, WhatsApp, or Telegram.

🔑 Setting up your first API key

If the dashboard shows UNHEALTHY on first run, PocketPaw is usually installed correctly. You just need to configure at least one model provider (API key or local provider).

Open Settings > API Keys in the dashboard.
Add a key for at least one provider:
- Anthropic: console.anthropic.com/settings/keys
- OpenAI: platform.openai.com/api-keys
- Google Gemini: aistudio.google.com/apikey
Save settings and retry your chat.

[!TIP] Power users / Docker / headless: You can also set API keys via environment variables instead of the dashboard. Use POCKETPAW_ANTHROPIC_API_KEY, POCKETPAW_OPENAI_API_KEY, or POCKETPAW_GOOGLE_API_KEY. See Configuration for the full list.

Prefer a free local option? Use Ollama instead (see Features and Configuration).

Features

| | | | --- | --- | | 📡 9+ Channels | Web Dashboard, Discord, Slack, WhatsApp, Telegram, Signal, Matrix, Teams, Google Chat | | 🧠 6 Agent Backends | Claude Agent SDK, OpenAI Agents, Google ADK, Codex CLI, OpenCode, Copilot SDK | | 🛠️ 50+ Tools | Browser, web search, image gen, voice/TTS/STT, OCR, research, delegation, skills | | 🔌 Integrations | Gmail, Calendar, Google Drive & Docs, Spotify, Reddit, MCP servers | | 💾 Memory | Long-term facts, session history, smart compaction, Mem0 semantic search | | 🔒 Security | Guardian AI, injection scanner, tool policy, plan mode, audit log, self-audit daemon | | 🏠 Local-First | Runs on your machine. Ollama for fully offline operation. macOS / Windows / Linux. |

Examples

You:  "Every Sunday evening, remind me which recycling bins to put out"
Paw:  Done. I'll check the recycling calendar and message you every Sunday at 6pm.

You:  "Find that memory leak, the app crashes after 2 hours"
Paw:  Found it. The WebSocket handler never closes connections. Here's the fix.

You:  "I need a competitor analysis report for our product launch"
Paw:  3 agents working on it. I'll ping you when it's ready.

Architecture

Everything goes through an event-driven message bus. Channels publish message

Pocketpaw

Install / Use

README