Installation

Requirements

• Python 3.10 or later
• uv (recommended) or pip

Install from PyPI

uv (recommended)pip

uv tool install potpie

python3 -m pip install --user potpie

Note

uv tool install potpie is recommended for CLI installs because global mutation of Python packages is generally not recommended.

Verify installation

potpie --version

First-time setup

After installing, run the setup wizard:

potpie setup

This provisions:

• Local configuration and storage
• The background daemon
• A default pot (workspace)
• Agent skills for your chosen harness

To target a specific repo and harness:

potpie setup --repo . --agent claude

Self-hosted / local development

For running the full Potpie server stack locally (not just the CLI), see the self-hosting guide below.

Local server setup

Warning

This section covers running the full Potpie server locally. Most users only need the CLI installed via PyPI above.

Prerequisites:

• Docker installed and running
• Git
• Python 3.11+ with uv

Steps:

1. Clone the repository:

   git clone --recurse-submodules https://github.com/potpie-ai/potpie.git
   cd potpie
   

2. Configure your environment:

   cp .env.template .env
   

   Open .env and fill in the required values. See .env.template for all fields including LLM provider, database, Redis, and storage settings.

   Tip

   Using Ollama? Set LLM_PROVIDER=ollama and use ollama_chat/qwen2.5-coder:7b for both CHAT_MODEL and INFERENCE_MODEL.

3. Install dependencies:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   uv sync
   

4. Start all services:

   chmod +x scripts/start.sh
   ./scripts/start.sh
   

   The script starts Docker services, waits for PostgreSQL, applies migrations, starts the FastAPI app, and starts the Celery worker.

5. Verify the server:

   curl -X GET 'http://localhost:8001/health'
   

To stop all services:

./scripts/stop.sh

Updating

uvpip

uv tool upgrade potpie

python3 -m pip install --upgrade potpie