Skip to main content
This guide covers running Pwnbook locally from the source repository — without Docker images. Infrastructure (PostgreSQL and Redis) still runs in Docker, but the frontend, backend, and workers run as native processes for hot-reload and easier debugging.

​
Prerequisites

​
Clone the repository

​
Configure the backend

Edit backend/.env. The .env.example file in the repository contains all available options with inline comments. At minimum, set:
  • DATABASE_URL — PostgreSQL connection string pointing to your local instance
  • REDIS_URL — Redis connection string
  • SESSION_SECRET — any random string for local development
  • AUTH_PROVIDER — set to local for local development
  • ADMIN_EMAIL / ADMIN_PASSWORD — credentials for the auto-seeded admin account
The frontend proxies /api and /auth to http://localhost:3001 automatically in development — you do not need to set VITE_API_URL.

​
Authentication in local development

​
Local auth (default)

Set AUTH_PROVIDER=local in backend/.env. Pwnbook seeds a default admin account on first startup: You can override these by setting ADMIN_EMAIL and ADMIN_PASSWORD in your .env.

​
WorkOS auth

Set AUTH_PROVIDER=workos and supply your WorkOS credentials:
WorkOS requires a publicly reachable redirect URI. For local development, use a tool like ngrok to tunnel your local backend, then register the tunnel URL as the redirect URI in your WorkOS dashboard.

​
Start everything

The dev.sh script starts all services in one step with colored, labeled output:
This will:
  1. Start PostgreSQL and Redis via Docker Compose
  2. Launch the backend on port 3001 (with hot reload)
  3. Launch the frontend on port 8080 (with Vite HMR)
  4. Print combined logs with color-coded prefixes
  5. Clean up all processes on Ctrl+C

​
Option B: Manual startup

Start infrastructure first:
Install dependencies (first run only):
Run database migrations:
Then start backend and frontend in separate terminals:
The app will be available at http://localhost:8080.

​
Database management

​
Migrations

After pulling changes that include new migrations:

​
Export and import

Useful for moving data between machines or creating snapshots:

​
Running the workers (optional)

The recon and AI workers are optional for most development tasks. Enable them if you are working on recon automation, AI chat, or background job processing. Each worker directory contains a .env.example with the required variables. Install dependencies with pip install -r requirements.txt and refer to the worker’s README for startup instructions. Alternatively, start both workers alongside infrastructure with Docker Compose:

​
Running tests

​
Frontend

​
Backend

​
Desktop app (Electron)

To run the desktop application locally:
This launches an Electron window pointed at your local Vite dev server. Ensure the frontend is already running. To build distributable desktop apps: