Skip to main content

Source Development Setup

This path runs ProPR from a source checkout with Docker Compose. Use it when changing ProPR code, running tests, validating docs, or building images. It is not required merely to evaluate ProPR on Apple Silicon; the prebuilt CLI and launcher path works through Docker Desktop's Linux amd64 emulation as described in Local Setup.

Prerequisites​

  • Node.js 22+
  • Git 2.25+
  • A maintained Docker Engine release and Docker Compose v2 (docker compose version; Docker Desktop includes both)
  • Redis, only if running services directly outside Docker Compose
  • A ProPR source checkout

Linux amd64 remains the native, recommended production path. On Apple Silicon macOS, Docker Desktop can run this development stack or the published Linux amd64 images under emulation; native arm64 images are not yet available.

1. Install Dependencies​

From the repository root:

npm ci

2. Create Host Directories​

Create the credential and cache directories that agent containers mount, before the first start — Docker otherwise creates missing mount sources as root-owned, which causes write failures:

mkdir -p ~/.claude ~/.codex ~/.gemini ~/.vibe /tmp/propr-vibe-prompts

The development Compose file mounts the fixed /tmp/propr-vibe-prompts path; the per-user /tmp/propr-vibe-prompts-$(id -u) default applies only to the CLI and launcher.

Log in to each agent you plan to run (for example claude auth login for Claude Code, agy login for Antigravity) so its credential directory holds real auth state.

3. Configure .env​

The Compose stack reads its configuration from .env in the repository root. Start from the shipped template:

cp .env.example .env

Then configure GitHub access. By default ProPR uses the shared, hosted ProPR GitHub App through the token relay — propr relay enroll writes the relay/routing credentials into the stack .env (run it from the repository root, or pass --root <dir> if another ProPR stack is configured on this machine) — and running your own GitHub App is the advanced alternative. See GitHub Authentication for both modes and the Configuration Reference for every variable.

4. Start The Development Compose Stack​

npm run compose:up    # docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d

The development Compose stack includes Redis. To enable the OpenCode agent, create ~/.config/opencode and ~/.local/share/opencode, then include the OpenCode override file:

docker compose -f docker-compose.yml -f docker-compose.opencode.yml up -d

5. Verify It Works​

Open http://localhost:5173 (override with UI_PORT), sign in with GitHub, and confirm the dashboard loads; the API answers on port 4000 (API_PORT). Tail the services if anything looks off:

npm run compose:logs

Then add a repository and enable an agent in the Web UI, or point the ProPR CLI at the dev stack with propr remote http://localhost:4000. npm run compose:down stops the stack.

Direct Local Services​

Direct service commands are mostly useful for debugging.

npm run daemon and npm run worker execute the compiled output in dist/, so build first:

npm run build
npm run daemon
npm run worker

Alternatively, run the TypeScript sources directly with tsx:

npm run daemon:dev
npm run worker:dev

If you run services directly, start Redis yourself first.

Docs Work​

cd docs
npm run typecheck
npm run build

Image Workflows​

npm run images:build
npm run images:smoke

Use the normal prebuilt-image setup for actual end-user installs.