> ## Documentation Index
> Fetch the complete documentation index at: https://docs.potpie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Setup

> Run Potpie locally on your own infrastructure.

## Before you begin

Make sure you have the following installed:

* [Docker](https://docker.com) installed and running
* [Git](https://git-scm.com) installed
* [Python 3.11+](https://python.org) with [uv](https://docs.astral.sh/uv/)

***

## Install Potpie

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone --recurse-submodules https://github.com/potpie-ai/potpie.git
    cd potpie
    ```
  </Step>

  <Step title="Configure your environment">
    ```bash theme={null}
    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.

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

  <Step title="Install dependencies">
    ```bash theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    uv sync
    ```

    This creates a `.venv` directory and installs all dependencies from `pyproject.toml`.
  </Step>

  <Step title="Start all services">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Verify the server is running">
    ```bash theme={null}
    curl -X GET 'http://localhost:8001/health'
    ```
  </Step>
</Steps>

To stop all services:

```bash theme={null}
./scripts/stop.sh
```

***

## Set up the frontend

```bash theme={null}
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)*

<ParamField body="GITHUB_APP_ID" type="string">
  Your GitHub App's numeric ID. Found in the app's settings page on GitHub.
</ParamField>

<ParamField body="GITHUB_PRIVATE_KEY" type="string">
  The private key generated when you created the GitHub App.
</ParamField>

Create a GitHub App in your organization with the following permissions, then set the variables above in `.env`:

| Scope                    | Permission     |
| ------------------------ | -------------- |
| Repository Contents      | Read only      |
| Repository Metadata      | Read only      |
| Repository Pull requests | Read and write |
| Repository Secrets       | Read only      |
| Repository Webhooks      | Read only      |
| Organization Members     | Read only      |
| Account Email address    | Read 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)*

<ParamField body="GH_TOKEN_LIST" type="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.

  ```bash theme={null}
  GH_TOKEN_LIST=ghp_token1,ghp_token2,ghp_token3
  ```
</ParamField>

***

**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`:

<ParamField body="CODE_PROVIDER" type="string">
  The Git provider to use. Accepted values: `github`, `gitbucket`.
</ParamField>

<ParamField body="CODE_PROVIDER_BASE_URL" type="string">
  Base URL of your self-hosted Git server's API.

  ```bash theme={null}
  CODE_PROVIDER_BASE_URL=http://your-git-server.com/api/v3
  ```
</ParamField>

<ParamField body="CODE_PROVIDER_TOKEN" type="string">
  Access token for your self-hosted Git server.
</ParamField>

<Note>
  `GH_TOKEN_LIST` tokens are always used for GitHub.com requests regardless of what `CODE_PROVIDER_BASE_URL` is set to.
</Note>

***

## Enable observability with Logfire *(optional)*

[Logfire](https://logfire.pydantic.dev) provides LLM trace monitoring for Potpie. Get a token at [logfire.pydantic.dev](https://logfire.pydantic.dev) and add it to `.env`:

<ParamField body="LOGFIRE_TOKEN" type="string">
  Your Logfire project token. Tracing is initialized automatically on startup once this is set. View traces at [logfire.pydantic.dev](https://logfire.pydantic.dev).
</ParamField>

<ParamField body="LOGFIRE_SEND_TO_CLOUD" type="boolean" default="true">
  Set to `false` to disable sending traces to Logfire cloud and keep all trace data local.
</ParamField>