Skip to main content

​
Before you begin

Make sure you have the following installed:

​
Install Potpie

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 values — see .env.template in the repository for all required and optional fields including LLM provider, database, Redis, and storage settings.Set isDevelopmentMode=enabled to parse local repositories directly, or isDevelopmentMode=disabled to use GitHub-connected repos.
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
This creates a .venv directory and installs all dependencies from pyproject.toml.
4

Start all services

chmod +x scripts/start.sh
./scripts/start.sh
The script starts Docker services, waits for PostgreSQL to be ready, applies database migrations, starts the FastAPI application, and starts the Celery worker.
5

Verify the server is running

curl -X GET 'http://localhost:8001/health'
To stop all services: 
./scripts/stop.sh

​
Set up the frontend

cd potpie-ui
cp .env.template .env
pnpm build && pnpm start

​
Configure GitHub authentication

Potpie supports three methods for accessing GitHub repositories. The method is selected automatically based on which environment variables are set. GitHub App (recommended for production)
​
GITHUB_APP_ID
string
Your GitHub App’s numeric ID. Found in the app’s settings page on GitHub.
​
GITHUB_PRIVATE_KEY
string
The private key generated when you created the GitHub App.
Create a GitHub App in your organization with the following permissions, then set the variables above in .env:
ScopePermission
Repository ContentsRead only
Repository MetadataRead only
Repository Pull requestsRead and write
Repository SecretsRead only
Repository WebhooksRead only
Organization MembersRead only
Account Email addressRead only
Once the app is created, select Install App from its sidebar and install it on your target organization or user account.
Personal Access Token Pool (recommended for development)
​
GH_TOKEN_LIST
string
A comma-separated list of GitHub personal access tokens with repo scope. Potpie randomly selects from the pool for load balancing. Each token allows 5,000 requests per hour.
GH_TOKEN_LIST=ghp_token1,ghp_token2,ghp_token3
Unauthenticated (public repositories only) No configuration required. Rate-limited to 60 requests per hour. Not recommended for anything beyond initial testing.

​
Use a self-hosted Git provider

For self-hosted Git servers such as GitBucket, set the following in .env:
​
CODE_PROVIDER
string
The Git provider to use. Accepted values: github, gitbucket.
​
CODE_PROVIDER_BASE_URL
string
Base URL of your self-hosted Git server’s API.
CODE_PROVIDER_BASE_URL=http://your-git-server.com/api/v3
​
CODE_PROVIDER_TOKEN
string
Access token for your self-hosted Git server.
GH_TOKEN_LIST tokens are always used for GitHub.com requests regardless of what CODE_PROVIDER_BASE_URL is set to.

​
Enable observability with Logfire (optional)

Logfire provides LLM trace monitoring for Potpie. Get a token at logfire.pydantic.dev and add it to .env:
​
LOGFIRE_TOKEN
string
Your Logfire project token. Tracing is initialized automatically on startup once this is set. View traces at logfire.pydantic.dev.
​
LOGFIRE_SEND_TO_CLOUD
boolean
default:"true"
Set to false to disable sending traces to Logfire cloud and keep all trace data local.