Setup

If the below steps do not work out for you, it would be great if you can open an issue on GitHub.

System Requirements

git to clone the forked repository
Node.js 24 to run the UI (we recommend using NVM on macOS/Linux or NVM for Windows on Windows to manage your node versions locally)
Python 3.13 to run the backend
Docker to run the database and redis cache locally

All commands below are shown for macOS / Linux. Expand the Windows tab for the PowerShell equivalent where it differs.

Steps

Fork the Peachdesk repository on GitHub
Clone your fork on your machine. You can skip --recurse-submodules here — the bootstrap script in the next step will initialize submodules for you.

git clone https://github.com/<GITHUB_HANDLE>/peachdesk
cd peachdesk

Run the contributor bootstrap. It configures origin (your fork) and upstream (peachdesk-hq/peachdesk), initializes the pipecat submodule, creates the Python venv, and copies the .env templates. Re-running it is safe — already-configured pieces are skipped.

bash scripts/setup_fork.sh

.\scripts\setup_fork.ps1

Activate the venv (the bootstrap script created it but won’t activate it for you):

source venv/bin/activate

.\venv\Scripts\Activate.ps1

Then install the repository’s push guard:

sh scripts/install-push-guard.sh

This installs a pre-push hook that refuses to push local development-memory refs (jollimemory/*) and agent checkpoint refs (refs/codex/*) to any remote — those refs hold raw development transcripts and full working-tree snapshots that must never leave your machine. The script is idempotent and preserves any hook blocks other tools have already installed; re-running it is safe. Re-run it after any AI-assistant tooling update that rewrites .git/hooks/. 4. Ensure you are on right version of Node.js using node --version

nvm use 24

Install UI dependencies

cd ui && npm install && cd ..

Start local docker services
Please ensure you dont have any other instance of conflicting services running by checking docker ps

docker compose -f docker-compose-local.yaml up -d

Verify that the processes have started by running docker ps

abhishek$ docker ps
CONTAINER ID   IMAGE         COMMAND                  CREATED          STATUS                    PORTS                                         NAMES
9066b7244b2f   postgres:17   "docker-entrypoint.s…"   18 seconds ago   Up 18 seconds (healthy)   0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp   peachdesk-postgres-1
6c7cb8afdf18   redis:7       "docker-entrypoint.s…"   18 seconds ago   Up 18 seconds (healthy)   0.0.0.0:6379->6379/tcp, [::]:6379->6379/tcp   peachdesk-redis-1
a57e3e92b02c   minio/minio   "/usr/bin/docker-ent…"   18 seconds ago   Up 18 seconds (healthy)   127.0.0.1:9000-9001->9000-9001/tcp            peachdesk-minio-1

Install Python requirements. The script installs api/requirements.txt and pipecat with the required extras. Add the dev flag if you also want the pipecat dev dependency group (pytest, ruff, pre-commit, etc.).

# Default (runtime only)
bash scripts/setup_requirements.sh

# Include pipecat dev dependencies
bash scripts/setup_requirements.sh --dev

# Default (runtime only)
.\scripts\setup_requirements.ps1

# Include pipecat dev dependencies
.\scripts\setup_requirements.ps1 -Dev

Start backend services

bash scripts/start_services_dev.sh

.\scripts\start_services_dev.ps1

Verify that your backend server is running

curl -X GET localhost:8000/api/v1/health

curl.exe http://localhost:8000/api/v1/health

You would be able to see the logs in logs/ directory.

tail -f logs/latest/*.log

Get-Content logs/latest/*.log -Wait

Restarting the backend

Re-run the same start script to restart. It reads the PID files under run/, terminates the previous services along with their descendants, and starts fresh ones.

bash scripts/start_services_dev.sh

.\scripts\start_services_dev.ps1

uvicorn runs with --reload --reload-dir api, so edits under api/ are picked up automatically — no restart needed. The other services (ari_manager, campaign_orchestrator, arq) do not auto-reload; re-run the start script after changing code they execute.

Start the UI

cd ui && npm run dev

You should be able to open the application on localhost:3000 now

New users default to the “Peachdesk” managed provider, which needs MANAGED_OPENAI_API_KEY, MANAGED_DEEPGRAM_API_KEY, and MANAGED_ELEVENLABS_API_KEY set in api/.env. Until they are set, calls fail with a 503. Alternatively, configure your own provider keys in /settings.

Keeping your fork in sync with upstream

The bootstrap script configures two remotes: origin (your fork, where you push) and upstream (peachdesk-hq/peachdesk, where new commits land). To pull in upstream changes:

git fetch upstream
git checkout main
git merge upstream/main          # or: git rebase upstream/main
git push origin main

Check your remotes any time with git remote -v. You should see:

origin    https://github.com/<YOUR_HANDLE>/peachdesk.git (fetch/push)
upstream  https://github.com/peachdesk-hq/peachdesk.git    (fetch/push)

Always push feature branches to origin (your fork), then open a pull request against peachdesk-hq/peachdesk:main. Never push directly to upstream.

Next Steps

We ship with AGENTS.md and CLAUDE.md which will help the Coding Agents get started quickly with the codebase. This should help your favourite coding agents to be able to navigate the codebase quickly and you can make changes to it and suit your specification better.

Guides

SDKs

Deployment

Contribution

System Requirements

Steps

Restarting the backend

Keeping your fork in sync with upstream

Next Steps

​System Requirements

​Steps

​Restarting the backend

​Keeping your fork in sync with upstream

​Next Steps

System Requirements

Steps

Restarting the backend

Keeping your fork in sync with upstream

Next Steps