Local Setup

Use this path to run ProPR on your own machine from prebuilt Docker images. Linux amd64 is the native, recommended production path. ProPR has also been exercised successfully on Apple Silicon macOS through Docker Desktop running the published Linux amd64 images under emulation; native arm64 images are not yet available.

The end state: ProPR runs from the prebuilt images on your workstation, the Web UI is at http://localhost:5173, the API listens on port 4000, and issue intake streams in over the hosted ProPR GitHub App's WebSocket routing — no inbound public URL and no GitHub App private key to manage.

Prerequisites

• A host that meets the system requirements: Linux amd64 for the native path, or Apple Silicon macOS with Docker Desktop running Linux containers and the published amd64 images under emulation. The Docker CLI and daemon must be reachable, and the default Docker socket must be available to the CLI and launcher.
• GitHub access for the backend. By default ProPR uses the shared, hosted ProPR GitHub App through Connect; install the GitHub CLI (gh) for setup's default browser login, or run propr login <token> first. Running your own GitHub App is the advanced alternative — see GitHub Authentication.
• A provider account for at least one coding agent — reuse host credentials, run propr agent login <agent>, or log in directly while adding the agent in the Web UI
• Node.js 22+ for the recommended CLI path (the launcher-container alternative needs no Node.js)
• Reserve 20 GB of free disk for images, data, logs, and repository workspaces; allow more for large repositories and image upgrades

Prepare Existing Agent Credentials (Optional)

Skip this section if you will choose Log in to a new account while adding the agent in the Web UI; ProPR creates and maps an isolated credential directory automatically. To reuse a CLI account already on this host, authenticate it before starting the stack. For Claude Code:

npm install -g @anthropic-ai/claude-code
claude auth login

For Antigravity, install the official CLI and complete a login on the host:

curl -fsSL https://antigravity.google/cli/install.sh | bash
agy login

Antigravity stores CLI configuration and credentials under ~/.gemini. Use equivalent setup for Codex (~/.codex) if you plan to enable it.

OpenCode

OpenCode keeps configuration under ~/.config/opencode and auth state from opencode auth login under ~/.local/share/opencode. ProPR reads both locations through two settings — HOST_OPENCODE_XDG_DIR (usually $HOME/.config/opencode) and HOST_OPENCODE_DATA_DIR (usually $HOME/.local/share/opencode) — set in .env on the CLI path, or passed as -e flags on the launcher path.

Mistral Vibe

Vibe authenticates either through ~/.vibe (HOST_VIBE_DIR) or a MISTRAL_API_KEY value in .env. Vibe also requires a prompt cache directory that must exist on the host before you start the stack:

mkdir -p "/tmp/propr-vibe-prompts-$(id -u)"

/tmp/propr-vibe-prompts-$(id -u) is the default host path and /tmp/propr-vibe-prompts the in-container path. Override with HOST_VIBE_PROMPT_CACHE_DIR (host) and VIBE_PROMPT_CACHE_DIR (container) only when needed.

Set Up And Start With The CLI (Recommended)

The ProPR CLI is the stack control plane — it scaffolds the runtime directory, verifies the host, and starts the stack. The quickest way to get everything running is the guided propr setup wizard:

npm install -g propr-cli      # Node.js 22+ — prefix sudo if your global npm needs it
which propr && propr --version # confirm the CLI is on PATH (catches root/user prefix mismatches)

mkdir propr-deploy && cd propr-deploy
propr setup                    # guided wizard: scaffold, verify, configure GitHub + intake, start

Global install permissions

If npm install -g fails with EACCES, your Node was installed where the global prefix is root-owned (a system/apt install) — prefix the command with sudo. Use the same convention every time you install or update the CLI: a sudo install must be updated with sudo, and a user-prefix install (e.g. nvm, or a custom npm config set prefix) needs no sudo. Mixing the two can update a different copy of the CLI or leave root-owned files in a user-owned prefix.

propr setup walks through every step interactively: it scaffolds .env + data/ logs/ repos/, detects the agent credentials you prepared above, pulls images, enrolls the default hosted ProPR GitHub App through ProPR Connect, starts the stack, restricts triggers to the authenticated GitHub user, and can add a first repository and open the Web UI. It can also offer the bundled ProPR Operator Agent Skill for detected Codex, Claude Code, Antigravity, OpenCode, and Vibe installations; installation is opt-in. On a clean install, accepting the defaults performs the GitHub login and App-install handoff when needed, writes the relay/routing credentials to .env, and configures Connect for browser login at the local UI; no separate OAuth App or propr relay enroll command is required. Setup is safe to re-run at any time: it skips already-satisfied steps and never overwrites existing configuration or data.

Over SSH or in terminals without raw-mode support, add --no-tui for line-by-line prompts. When stdin is a pipe or CI stream, setup cannot prompt — use the manual flow below instead.

Manual / Advanced Flow

If you prefer to control each step yourself (for scripting, CI, or troubleshooting), run the underlying commands that propr setup orchestrates, in this order.

1. Scaffold the runtime directory:

propr init stack               # creates .env + data/ logs/ repos/, detects agent credentials

propr init stack writes .env from the bundled template and auto-detects agent credential directories on the host (~/.claude, ~/.codex, ~/.gemini, ~/.config/opencode, ~/.vibe). The template defaults to the hosted ProPR GitHub App over WebSocket routing (GITHUB_EVENT_INTAKE_MODE=routing_websocket).

2. Configure GitHub access in .env. On the default path, install the shared ProPR GitHub App on your repositories, then run propr login and propr relay enroll from the stack directory — enrollment proves your identity with the GitHub token from propr login and writes the relay/routing credentials and GH_INSTALLATION_ID straight into .env, with no GitHub App or private key of your own. Running your own GitHub App is the advanced alternative (App permissions, GH_APP_ID, GH_INSTALLATION_ID, HOST_GH_PRIVATE_KEY); GitHub Authentication covers both modes in full.

Own-App path: use HOST_GH_PRIVATE_KEY

Point HOST_GH_PRIVATE_KEY at the .pem on the host. Both propr start and the launcher alternative bind-mount it into the app containers and set GH_PRIVATE_KEY_PATH for you. A hand-set GH_PRIVATE_KEY_PATH must resolve inside the app containers (for example a key staged under data/), so a host path or a path inside the launcher container does not work there.

If you take the own-App path, register the App with these repository permissions and install it on every repository ProPR should process:

Permission	Access
Contents	Read and write
Metadata	Read-only
Issues	Read and write
Pull Requests	Read and write
Actions	Read-only (optional; used to read CI check results). Read and write is required only for the per-repository "Cancel CI while follow-up implementation is in progress" option

3. Edit the rest of .env. The relevant local-stack values:

DASHBOARD_API_PORT=4000
FRONTEND_URL=http://localhost:5173
SESSION_SECRET=generate-a-strong-secret-here

PRIMARY_PROCESSING_LABELS=AI,propr
GITHUB_BOT_USERNAME=your_bot_username

GIT_CLONES_BASE_PATH=/tmp/git-processor/clones
GIT_WORKTREES_BASE_PATH=/tmp/git-processor/worktrees
GIT_DEFAULT_BRANCH=main
DB_FILENAME=./data/propr.sqlite

# Custom GitHub web login only; relay-enrolled stacks sign in through Connect.
# GH_OAUTH_CLIENT_ID=your_github_oauth_client_id
# GH_OAUTH_CLIENT_SECRET=your_github_oauth_client_secret
# GH_OAUTH_CALLBACK_URL=http://localhost:4000/api/auth/github/callback

Issue intake defaults to the hosted App's WebSocket routing: events stream to ProPR over an outbound WebSocket with near-immediate delivery, so there is no inbound public URL to expose. Polling and your own GitHub App webhook remain available as advanced intake options — see Server Setup and Deployment.

4. Check and start:

propr check                    # verifies Docker, images, agents, and GitHub auth mode
propr start                    # pulls images and starts the stack with a live dashboard

propr check --verify additionally smoke-tests each agent image. propr start --no-tui is the non-interactive form for scripts.

ProPR Data Folder Layout

After the first run, the directory looks like this:

propr-deploy/
├── .env                        # configuration — written by the setup wizard / propr init stack
├── your-app-private-key.pem    # own-GitHub-App path only; absent on the default relay path
├── data/                       # SQLite database and persistent state
├── logs/                       # service logs
└── repos/                      # repository mount for the worker

Repository clones and per-task worktrees live outside this folder: by default under /tmp/git-processor/clones and /tmp/git-processor/worktrees on the host (GIT_CLONES_BASE_PATH, GIT_WORKTREES_BASE_PATH), a path the stack and agent containers mount at the same location.

Verify It Works

Confirm the stack is alive before moving on:

propr status                   # all local stack containers should be running

Open http://localhost:5173, sign in with GitHub, and confirm the dashboard loads. The API answers on port 4000. Then finish configuration from the Web UI (add a repository, enable an agent) — or from the CLI:

propr remote http://localhost:4000
propr login                      # reuses your gh CLI session, or pass a PAT
propr repo add owner/repo -b main
propr agent add my-claude -t claude -m opus5 -d opus5
propr use owner/repo
propr remote-status              # verify daemon, workers, Redis, GitHub auth

From here, propr plan create "..." --wait and propr issue implement <draft-id>/1 --wait run the same plan-to-PR flow as the Web UI. propr stop shuts the stack down.

Alternative: Launcher Container Without The CLI

If you prefer to keep Node.js off the host, the propr/launcher:latest container runs the same orchestrator. Create the runtime directory and .env manually (mkdir -p propr-deploy/{data,logs,repos}, write .env, place the key if you run your own App), then run the docker run command documented in Server Setup → Start The Launcher — it is identical for a local machine. All PROPR_* and HOST_* paths must be absolute; the launcher does not expand ~.

Optional: Drive This Stack From The Hosted UI

By default a local stack is reached at http://localhost:5173. If you would rather use the hosted ProPR UI at https://app.propr.dev to drive your local stack, enable the optional hosted UI tunnel — a managed Cloudflare Tunnel sidecar (the official cloudflare/cloudflared image) that publishes this stack to the hosted control plane. It is off by default, so plain localhost use is unaffected.

In brief: provision a tunnel in ProPR Connect, copy the one-time CLI command it shows, and run it in your stack:

propr tunnel setup --token <connector-token> --url https://t-<id>.propr.dev --start

The setup command writes the required tunnel settings to your stack .env (hosted CORS origin, public API URL, proxy-host OAuth callback); with --start it recreates a running stack so the API picks up the hosted URLs immediately. The architecture — which paths the proxy routes, browser origin vs API host, and the full config block — lives in Production Deployment → Hosted UI Tunnel; the commands are covered in ProPR CLI → Hosted UI Tunnel.

Update ProPR

Service images are pinned to the release version of the control plane that starts them.

• CLI path: update the CLI, then restart from the stack directory so it acts on the right runtime root — propr start pulls the matching images (npm update -g propr-cli && cd propr-deploy && propr start --restart). propr start --restart resolves the stack relative to the current directory (or --root <dir>), so run it from propr-deploy to avoid restarting against the wrong path.
• Launcher path: docker pull propr/launcher:latest, then re-run the docker run command; the launcher pulls the matching service images.

Data, logs, and repositories persist in your runtime directory either way.