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

  1. Fork the Peachdesk repository on GitHub
  2. 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
  1. 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
Activate the venv (the bootstrap script created it but won’t activate it for you): 
source venv/bin/activate
  1. Ensure you are on right version of Node.js using node --version
nvm use 24
  1. Install UI dependencies
cd ui && npm install && cd ..
  1. 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
  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
  1. Start backend services
bash scripts/start_services_dev.sh
Verify that your backend server is running 
curl -X GET localhost:8000/api/v1/health
You would be able to see the logs in logs/ directory. 
tail -f logs/latest/*.log

​
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
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.
  1. Start the UI
cd ui && npm run dev
  1. 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.