By the end of this guide, you will have a fully configured local workspace running LeadForge OS in development mode.

Prerequisites

Node.js: Version 18.0.0 or higher (v20.x or v22.x LTS recommended). Verify with node -v.
pnpm: Version 8.0.0 or higher. Verify with pnpm -v.
Git: Installed and configured. Verify with git --version.
Ollama (optional): Installed locally for offline, private lead qualification. Verify with ollama --version.

Setup Steps

Clone the repository and navigate to the project root:

bash

git clone https://github.com/kjxcodez/leadforge-os.git
cd leadforge-os

Install all dependencies across the monorepo workspace:
bash
```
pnpm install
```
Build all workspace packages and schema dependencies:
bash
```
pnpm build
```
Launch the local development environment:
bash
```
pnpm dev
```
This launches the REST API server and the Electron application concurrently. You can start specific applications selectively using Turborepo filters:
bash
```
# Start Hono REST API server only
pnpm dev --filter=api
 
# Start Electron Desktop UI only
pnpm dev --filter=@leadforge/desktop
```

Upon first launch, the desktop application should open a React-based Chromium window and automatically:

Initialize the workspace database in the local directory (userData/workspaces under AppData/Roaming/leadforge on Windows).
Execute SQL migrations to initialize the CRM database schemas.
Seed mock data representing company, contact, and email outreach records.

Confirm that the application starts successfully and visualizes the dashboard.

If you encounter native binary compilation errors (e.g. better-sqlite3.node was compiled against a different Node.js version), run:

bash

pnpm -F @leadforge/desktop exec electron-builder install-app-deps

For other issues, see the Troubleshooting Guide.