pocketpaw.xyz

Your AI agent in 30 seconds. Not 30 hours. Self-hosted, open-source personal AI with desktop installer, multi-agent Command Center(Deep Work), and 7-layer security. Anthropic, OpenAI, or Ollama.

<p align="center"> <img src="paw.png" alt="PocketPaw" width="100"> </p> <h1 align="center">🐾 PocketPaw</h1> <p align="center"> <strong>An AI agent that runs on your machine, not someone else's.</strong> </p> <p align="center"> <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> </p> <p align="center"> <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> </p> <p align="center"> Self-hosted AI agent with a native desktop app and web dashboard. Talks to you over <strong>Discord</strong>, <strong>Slack</strong>, <strong>WhatsApp</strong>, <strong>Telegram</strong>, or the browser.<br> No subscription. No cloud lock-in. Your data stays on your machine. </p>

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

<p align="center"> <video src="https://github.com/user-attachments/assets/a15bb8c7-6897-40d2-8111-aa905fe3fdfe" width="700" controls></video> </p>

---

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.

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:

BASH
pip install pocketpaw && pocketpaw  

Recommended install (with virtual environment):

BASH
# 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:

BASH
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
powershell -NoExit -Command "iwr -useb https://pocketpaw.xyz/install.ps1 | iex"  

Option B — Manual install:

1. Open PowerShell and verify Python version (must be 3.11+):

   POWERSHELL
   python --version  
   

2. Upgrade pip:

   POWERSHELL
   python -m pip install --upgrade pip  
   

3. (Optional but recommended) Create and activate a virtual environment:

   POWERSHELL
   python -m venv pocketpaw-env  
   .\pocketpaw-env\Scripts\Activate.ps1  
   

4. Install PocketPaw:

   POWERSHELL
   pip install pocketpaw  
   

5. Verify the installation by running:

   POWERSHELL
   pocketpaw --help  
   

   Or start the dashboard:

   POWERSHELL
   pocketpaw  
   

Windows Troubleshooting

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

TEXT
'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:

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

Find your exact Scripts path:

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

How to fix:

1. Open Start → Search "Environment Variables"
2. Click "Edit the system environment variables"
3. Click "Environment Variables"
4. Under User variables → Select Path → Click Edit
5. Add the Scripts directory path
6. Restart your terminal

Alternatively, run PocketPaw without adding Scripts to PATH:

POWERSHELL
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>

BASH
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>

BASH
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:

BASH
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.

<a id="api-key-setup"></a>

🔑 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).

1. Open Settings > API Keys in the dashboard.
2. 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
3. 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

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

<p align="center"> <img src="docs/public/pocketpaw-system-architecture.webp" alt="PocketPaw System Architecture" width="800"> </p>

Everything goes through an event-driven message bus. Channels publish messages, the AgentLoop picks them up and routes to whichever backend you've configured. All six backends implement the same AgentBackend protocol, so swapping one for another doesn't touch the rest of the system.

The desktop client (client/) is a Tauri 2.0 + SvelteKit app that connects to the Python backend over REST and WebSocket. It provides system tray integration, global hotkeys, multi-window support (side panel, quick ask), and an onboarding wizard that handles backend installation.

Agent Backends

Security

<p align="center"> <img src="docs/public/pocketpaw-security-stack.webp" alt="PocketPaw 7-Layer Security Stack" width="500"> </p>

PocketPaw uses a secondary LLM (Guardian AI) to review every tool call before execution. Our security stack includes:

• Injection Scanning & configurable tool policies.
• Plan Mode for mandatory human approval.
• --security-audit CLI for manual reviews.
• Self-audit Daemon with append-only audit logs.

[!TIP]
Full details and configuration options are available in the Security Documentation or on the official website.

<details> <summary>Detailed security architecture</summary> <br> <p align="center"> <img src="docs/public/pocketpaw-security-architecture.webp" alt="PocketPaw Security Architecture (Defense-in-Depth)" width="800"> </p> </details>

---

Configuration

Settings live in ~/.pocketpaw/config.json. You can also use POCKETPAW_-prefixed env vars or the dashboard Settings panel. API keys are encrypted at rest.

Environment Variables (.env file)

PocketPaw ships with a .env.example file that lists every supported environment variable with inline comments. Before running PocketPaw (especially when cloning from source or using Docker), copy it to .env and fill in the values you need:

BASH
# macOS / Linux  
cp .env.example .env

# Windows (PowerShell)  
Copy-Item .env.example .env  

Then open .env in your editor and uncomment / set the variables relevant to your setup. For example:

DOTENV
# LLM provider  
POCKETPAW_ANTHROPIC_API_KEY=sk-ant-...  
POCKETPAW_AGENT_BACKEND=claude_agent_sdk   # or openai_agents, google_adk, etc.

# Optional: Telegram bot  
POCKETPAW_TELEGRAM_BOT_TOKEN=...  
POCKETPAW_ALLOWED_USER_ID=...  

Tip: Variables set in .env are loaded automatically at startup. You can also export them directly in your shell or set them via the dashboard Settings panel — all three methods work interchangeably.

Alternatively, export variables directly in your shell:

BASH
export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..."   # Required for Claude SDK backend  
export POCKETPAW_AGENT_BACKEND="claude_agent_sdk"  # or openai_agents, google_adk, etc.  

Note: An Anthropic API key from console.anthropic.com is required for the Claude SDK backend. OAuth tokens from Claude Free/Pro/Max plans are not permitted for third-party use. For free local inference, use Ollama instead.

See the full configuration reference for all settings.

---

Development

Backend (Python)

Prerequisites:

• Python 3.11 or higher (download here)
• uv package manager

Install uv:

[!WARNING]
Windows users: You must open a new terminal window after running the install script below before uv will be recognized. The installer updates your PATH, but this change does not apply to your current terminal session — running uv immediately after install will give a CommandNotFoundException error.

BASH
# macOS/Linux  
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)  
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip  
pip install uv  

[!TIP]
Windows: To use uv immediately without opening a new terminal, run:

POWERSHELL
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"  

Then verify the installation: uv --version

Setup and run:

BASH
# 1. Verify Python version  
python3 --version

# 2. Clone and enter the repository  
git clone https://github.com/pocketpaw/pocketpaw.git && cd pocketpaw

# 3. Install with dev dependencies  
uv sync --dev

# 4. Run PocketPaw in development mode (auto-reload)  
uv run pocketpaw --dev

# 5. Run tests  
uv run pytest --ignore=tests/e2e    # Run tests (2900+)

# 6. Lint & format  
uv run ruff check . && uv run ruff format .  

<details> <summary>Optional extras</summary>

BASH
pip install pocketpaw[openai-agents]       # OpenAI Agents backend  
pip install pocketpaw[google-adk]          # Google ADK backend  
pip install pocketpaw[discord]             # Discord  
pip install pocketpaw[slack]               # Slack  
pip install pocketpaw[memory]              # Mem0 semantic memory  
pip install pocketpaw[all]                 # Everything  

</details>

Desktop Client (Tauri + SvelteKit)

The native desktop app lives in client/. It connects to the Python backend via REST/WebSocket.

Prerequisites:

• Bun (package manager)
• Rust (for Tauri)
• Python backend running on localhost:8888

BASH
cd client  
bun install                    # Install dependencies  
bun run dev                    # Vite dev server (http://localhost:1420)  
bun run tauri dev              # Full desktop app (frontend + Tauri shell)  
bun run check                  # Type check  
bun run tauri build            # Production build  

Tech stack: SvelteKit 2 + Svelte 5, Tailwind CSS 4, shadcn-svelte, Tauri 2.0 (Rust). See client/CLAUDE.md for full architecture details.

---

Documentation

pocketpaw.xyz covers getting started, backends, channels, tools, integrations, security, memory, and the full API reference.

---

Star History

<a href="https://star-history.com/#pocketpaw/pocketpaw&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=pocketpaw/pocketpaw&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=pocketpaw/pocketpaw&type=Date" /> <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=pocketpaw/pocketpaw&type=Date" /> </picture> </a>

Contributors

<a href="https://github.com/pocketpaw/pocketpaw/graphs/contributors"> <img src="https://contrib.rocks/image?repo=pocketpaw/pocketpaw" alt="Contributors" /> </a>

---

Join the Pack

• Twitter: @prakashd88
• Discord: discord.gg/asRrtm95Zc
• Email: pocketpawai@gmail.com

PRs welcome. Come build with us.

License

MIT © PocketPaw Team

<p align="center"> <img src="paw.png" alt="PocketPaw" width="40"> <br> <strong>Built for people who'd rather own their AI than rent it</strong> </p>

Source: https://github.com/pocketpaw/pocketpaw