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

RequirementVersionNotes
Node.js22.xBackend and frontend
Python3.11+Recon and AI workers
Docker & Docker Compose24.0 / v2.20+For PostgreSQL and Redis
GitAnyTo clone the repository

​
Clone the repository

git clone https://github.com/pwnbook/pwnbook.git
cd pwnbook

​
Configure the backend

cp backend/.env.example backend/.env
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:
FieldDefault
Emailadmin@local.net
Password@dminUser
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: 
AUTH_PROVIDER=workos
WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...
WORKOS_REDIRECT_URI=http://localhost:3001/auth/callback
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: 
./dev.sh
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: 
docker compose up -d db redis
Install dependencies (first run only): 
npm install
cd backend && npm install && cd ..
Run database migrations: 
cd backend && npm run db:migrate && cd ..
Then start backend and frontend in separate terminals: 
# Terminal 1 — backend
cd backend && npm run dev

# Terminal 2 — frontend
npm run dev
The app will be available at http://localhost:8080.

​
Database management

​
Migrations

After pulling changes that include new migrations: 
cd backend && npm run db:migrate

​
Export and import

Useful for moving data between machines or creating snapshots: 
# Export (creates a timestamped archive)
cd backend && npm run db:export

# Import a previously exported archive
cd backend && npm run db:import

​
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: 
docker compose up -d db redis recon-worker ai-worker

​
Running tests

​
Frontend

npm test

​
Backend

cd backend && npm test

​
Desktop app (Electron)

To run the desktop application locally: 
npm run electron-dev
This launches an Electron window pointed at your local Vite dev server. Ensure the frontend is already running. To build distributable desktop apps: 
npm run build:mac    # macOS .dmg
npm run build:win    # Windows installer
npm run build:linux  # Linux AppImage