> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pwnbook.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Run Pwnbook from source for development, testing, or contributing to the project.

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

| Requirement             | Version       | Notes                    |
| ----------------------- | ------------- | ------------------------ |
| Node.js                 | 22.x          | Backend and frontend     |
| Python                  | 3.11+         | Recon and AI workers     |
| Docker & Docker Compose | 24.0 / v2.20+ | For PostgreSQL and Redis |
| Git                     | Any           | To clone the repository  |

## Clone the repository

```bash theme={null}
git clone https://github.com/pwnbook/pwnbook.git
cd pwnbook
```

## Configure the backend

```bash theme={null}
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

<Note>The frontend proxies `/api` and `/auth` to `http://localhost:3001` automatically in development — you do not need to set `VITE_API_URL`.</Note>

## Authentication in local development

### Local auth (default)

Set `AUTH_PROVIDER=local` in `backend/.env`. Pwnbook seeds a default admin account on first startup:

| Field    | Default           |
| -------- | ----------------- |
| Email    | `admin@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:

```bash theme={null}
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](https://ngrok.com) to tunnel your local backend, then register the tunnel URL as the redirect URI in your WorkOS dashboard.

## Start everything

### Option A: Using the dev script (recommended)

The `dev.sh` script starts all services in one step with colored, labeled output:

```bash theme={null}
./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:

```bash theme={null}
docker compose up -d db redis
```

Install dependencies (first run only):

```bash theme={null}
npm install
cd backend && npm install && cd ..
```

Run database migrations:

```bash theme={null}
cd backend && npm run db:migrate && cd ..
```

Then start backend and frontend in separate terminals:

```bash theme={null}
# Terminal 1 — backend
cd backend && npm run dev

# Terminal 2 — frontend
npm run dev
```

The app will be available at [http://localhost:8080](http://localhost:8080).

## Database management

### Migrations

After pulling changes that include new migrations:

```bash theme={null}
cd backend && npm run db:migrate
```

### Export and import

Useful for moving data between machines or creating snapshots:

```bash theme={null}
# 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:

```bash theme={null}
docker compose up -d db redis recon-worker ai-worker
```

## Running tests

### Frontend

```bash theme={null}
npm test
```

### Backend

```bash theme={null}
cd backend && npm test
```

## Desktop app (Electron)

To run the desktop application locally:

```bash theme={null}
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:

```bash theme={null}
npm run build:mac    # macOS .dmg
npm run build:win    # Windows installer
npm run build:linux  # Linux AppImage
```