PocketPaw: a self-hosted AI agent you install with pip install pocketpaw

What PocketPaw is for, and who it is not for

The pitch in the README is narrow and clear: an AI agent that runs on your machine, not someone else's. PocketPaw is a personal assistant process you host yourself. It holds the model credentials, it holds the conversation, and it exposes itself to you through channels you already use: Discord, Slack, WhatsApp, Telegram, or a browser dashboard. The desktop client adds a system tray, global shortcuts and multi-window support, but the backend is a Python package.

The intended audience is an individual or a small team that wants an agent with persistent memory and tool access without handing the keys to a hosted service. The pyproject classifiers list End Users/Desktop alongside Developers, which matches the two install paths: a signed desktop installer for people who do not want a terminal, and pip for people who do.

It is a poor fit if you need a stable API surface. The README carries a beta warning and states that breaking changes between versions should be expected, and the release history supports that reading: v0.4.15, v0.4.16 and v0.4.18 landed between March and late April 2026. If you are building a product on top of it rather than running it for yourself, the version churn is the first thing to price in.

How the agent, the backends and the connectors fit together

PocketPaw separates three things that are often fused in agent projects: the model provider, the agent backend, and the chat connector.

The model provider is chosen with POCKETPAW_LLM_PROVIDER, whose documented values are auto, ollama, openai, anthropic, gemini and openai_compatible. Each has its own key and model variable, so POCKETPAW_ANTHROPIC_MODEL defaults to claude-sonnet-4-6 and POCKETPAW_OPENAI_MODEL defaults to gpt-4o in the example file.

The agent backend is a separate switch, POCKETPAW_AGENT_BACKEND, with values claude_agent_sdk, openai_agents, google_adk, codex_cli, opencode and copilot_sdk. This is the part that decides how tools get invoked and how the loop is driven. The Dockerfile makes the dependency concrete: it installs @anthropic-ai/claude-code and @openai/codex globally in a Node stage and copies them into the runtime image, so the CLI backends are present without a network fetch at container start.

The connectors are configured per platform. Telegram is the simplest, needing POCKETPAW_TELEGRAM_BOT_TOKEN and POCKETPAW_ALLOWED_USER_ID. Discord, Slack and WhatsApp each get their own token variables and allow-lists, including channel and guild restrictions. There is no single "enable everything" switch, which is deliberate: each channel you turn on is another inbound path to an agent that can run tools.

The pyproject release note for 0.4.18 lists security work in the same breath as feature work: a file jail with OCR and STT, fail-closed scope enforcement, an SSRF guard, PII tightening, audit-log scrubbing and nonce-based CSP. That is the shape of the project's 7-layer security claim. It is also a reminder that the agent executes things, and the guardrails are being hardened release by release.

Installing PocketPaw and getting to a first answer

The README recommends the desktop app for most people, but the terminal path is the one that shows what is actually happening. Prerequisites are Python 3.11 or higher and pip.

The shortest install is a single line. The README gives it as-is:

pip install pocketpaw && pocketpaw

Running pocketpaw with no arguments starts the dashboard. If you prefer isolation, the documented sequence creates a virtual environment first:

python3 -m venv pocketpaw-env
source pocketpaw-env/bin/activate
pip install pocketpaw
pocketpaw

There are also pipx, uvx and from-source routes. The from-source path uses uv and expects a clone:

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

On first launch, the README warns that the health panel may show UNHEALTHY. That is expected until a model provider is configured; the application is running, only the AI features are disabled. To fix it, copy the example environment file and set a provider. The variable names all carry the POCKETPAW_ prefix:

cp .env.example .env
# then set, for example:
# POCKETPAW_LLM_PROVIDER=anthropic
# POCKETPAW_ANTHROPIC_API_KEY=...

The free route is Ollama. The example file points POCKETPAW_OLLAMA_HOST at http://ollama:11434 for Docker, and the compose file defines an ollama service behind a profile, started with docker compose --profile ollama up -d. On Windows, the README notes that browser automation and shell tools work best under WSL2, while the web dashboard and chat features run natively.

One practical gotcha is documented: if the pocketpaw command is not recognized after a pip install, the Python Scripts directory is probably missing from PATH. The README gives the diagnostic and the workaround:

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

If editing PATH is not appealing, python -m pocketpaw runs the same entry point.

The security model is real, and so is the blast radius

PocketPaw can run shell commands and drive a browser. The Dockerfile installs Playwright Chromium along with its shared libraries, plus tesseract for OCR, and the compose file mounts ./workspace into the container so files written by the Write and Bash tools land on the host at that path. Those are the capabilities that make the agent useful, and they are also the reason the 0.4.18 notes read like a security changelog.

The documented mitigations are worth reading literally rather than as marketing. Fail-closed scope enforcement means a missing scope denies rather than allows. An SSRF guard restricts what the agent can be pointed at. Audit-log scrubbing and a dynamic cookie Secure flag address what leaks out of the system rather than what gets in. None of this is a sandbox in the virtualisation sense. The agent runs as your user, with your files, and the compose memory limit of 8G with 4 CPUs bounds resource use, not permissions.

A second limitation is platform asymmetry. The README states plainly that some features work best under WSL2 and that native Windows support covers the web dashboard and LLM chat. If your workload depends on browser automation, plan for WSL2 or Linux rather than assuming parity.

The third is the beta status. The README says breaking changes between versions should be expected, and the release notes describe fixes to things like a rate-limiter race, ReDoS bounds and bus mutation leakage. Those are the kinds of defects that show up in a system still finding its edges. Running it for yourself on a machine you can rebuild is a different risk decision from running it against production credentials.

PocketPaw compared with wiring up an agent framework yourself

The obvious alternative is not another product but the do-it-yourself route: take the Anthropic or OpenAI SDK, add a tool loop, and put a Telegram bot in front of it. That path gives you exactly the behaviour you wrote and nothing else, and it is the right call if the agent is a component inside a larger application.

PocketPaw's difference is that the loop, the connectors and the persistence are already assembled. The .env.example exposes four chat platforms with per-platform allow-lists, a choice of six agent backends and six model providers, and optional Qdrant for semantic memory. Writing that yourself is a week of plumbing before the first useful answer. Using PocketPaw is an install command.

The trade is control. A hand-rolled loop has no opinion about scope enforcement or audit scrubbing because it has no scopes and no audit log. PocketPaw has both, which is good when you want them and friction when your access pattern does not match the model the project chose. The same applies to the backend abstraction: switching from claude_agent_sdk to openai_agents is a config change, but the behaviour of the agent changes with it, and the README does not claim the backends are interchangeable in results.

If you want a hosted assistant with a polished mobile app, neither path is what you want. PocketPaw is for people who specifically do not want that.

Maintenance, upgrades and the MIT licence

The last push to the repository was on 2026-09-10, and the most recent tagged release is v0.4.18 from 2026-04-29. The repository is not archived. That gap between the last release tag and the last push is worth noting on its own: development activity on main does not automatically become a version you can pin.

Upgrading is a pip operation, and the beta warning is the relevant policy. There is no documented migration guide, and the README does not describe a rollback procedure. If you run PocketPaw in Docker, the compose file keeps state in the pocketpaw-data volume at /home/pocketpaw/.pocketpaw, which is the thing to back up before pulling a new image. Agent-created files live in the separate ./workspace mount, so the two are separable.

The licence is MIT, declared both in the repository and in pyproject.toml. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the copyright notice and licence text are kept. It offers no patent grant and no warranty. That is the standard trade for this licence, and it is not legal advice; check how it interacts with your own distribution obligations.

The one licensing detail worth flagging is that the Dockerfile installs @anthropic-ai/claude-code and @openai/codex globally. Those are separate packages with their own terms, and PocketPaw's MIT licence does not cover them. If you use the codex_cli or claude_agent_sdk backends, you are also bound by whatever those tools require.

Editorial conclusion

Adopt PocketPaw if you want a personal agent on hardware you control, you are comfortable with a beta that warns about breaking changes, and you are willing to treat the machine it runs on as disposable. Do not adopt it if you need a frozen API surface or if your workload depends on native Windows browser automation, since the README points those features at WSL2. Before you commit, verify two things in your own environment: that the pocketpaw entry point resolves on PATH (the README documents the Scripts directory failure and the python -m pocketpaw fallback), and that your chosen POCKETPAW_AGENT_BACKEND is one whose CLI dependency you are prepared to install and license separately, because the Dockerfile pulls in @anthropic-ai/claude-code and @openai/codex outside the MIT grant.

Frequently asked questions

Official sources

1. License: MIT
2. pocketpaw/pocketpaw on GitHub
3. Project website
4. README
5. Releases