# How to Set Up Kaneo Locally for Development: Complete Setup Guide

> Learn how to set up Kaneo locally for development. Clone the repo, install dependencies, configure .env, and start the API and web app with hot-reload.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-29

---

**Clone the Kaneo repository, install dependencies with pnpm, configure the root `.env` file, and run `pnpm dev` to start the API at `http://localhost:1337` and the web app at `http://localhost:5173` with hot-reload enabled.**

Setting up Kaneo for local development requires configuring a pnpm-based monorepo that powers a self-hosted project management platform. This guide walks through the complete Kaneo local development setup using either Docker Compose or native tooling, with specific references to the source code structure in `usekaneo/kaneo`.

## Kaneo Architecture Overview

Kaneo follows a clean monorepo architecture with three primary components:

- **API layer** (`apps/api`) — Hono-powered API handling authentication, authorization, database operations, events, and WebSocket realtime delivery
- **Web layer** (`apps/web`) — React/Vite frontend consuming the typed client from shared libraries
- **Shared libraries** (`packages/libs`, `packages/permissions`) — Type-safe client, URL helpers, and permission definitions

Both the API and web application read from a single `.env` file at the project root, ensuring consistent environment variables across all packages.

## Prerequisites for Kaneo Local Development

Before starting, ensure you have:

- **Node.js** (LTS recommended)
- **pnpm** (the package manager used throughout the monorepo)
- **Git** for cloning the repository
- **Docker and Docker Compose** (optional, for containerized setup)

## Method 1: Native Development Setup

This approach runs the API and web app directly on your host with pnpm workspaces.

### Step 1: Clone the Repository

```bash
git clone https://github.com/usekaneo/kaneo.git
cd kaneo

```

### Step 2: Install Monorepo Dependencies

```bash
pnpm install

```

The `pnpm install` command resolves all workspace dependencies across `apps/api`, `apps/web`, and `packages/*`.

### Step 3: Configure Environment Variables

Copy the sample environment file and edit it:

```bash
cp .env.sample .env

```

Populate `.env` with at minimum these required values:

```text

# .env

KANEO_CLIENT_URL=http://localhost:5173
KANEO_API_URL=http://localhost:1337
AUTH_SECRET=super-secret-32-char-random-string
DATABASE_URL=postgresql://kaneo:password@localhost:5432/kaneo
POSTGRES_DB=kaneo
POSTGRES_USER=kaneo
POSTGRES_PASSWORD=password

```

The [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) file in the repository root documents all optional variables, including `REDIS_URL` for scaling realtime features.

### Step 4: Start Development Servers

```bash
pnpm dev

```

This command boots both services simultaneously:

- **API** → `http://localhost:1337` (entry point: [`apps/api/src/openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/openapi.ts))
- **Web** → `http://localhost:5173` (entry point: [`apps/web/src/main.tsx`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/main.tsx))

Changes to source files trigger automatic hot-reload in both services.

## Method 2: Docker Compose Setup

For a one-command development environment with PostgreSQL included, use Docker Compose.

### Step 1: Configure Environment

```bash
cp .env.sample .env

# Edit .env with your preferred values

```

### Step 2: Launch the Stack

```bash
docker compose -f compose.yml up -d

```

The [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) file provisions:
- PostgreSQL database container
- Kaneo application container

Access the UI at `http://localhost:5173` once containers are healthy.

For local customizations, the repository also provides [`compose.local.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.local.yml) as an override file.

## Key Source Files for Development

Understanding these entry points helps when navigating the Kaneo codebase:

| File | Purpose |
|------|---------|
| [`apps/api/src/openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/openapi.ts) | Central Hono router that registers all routes, Zod validators, and middleware |
| [`apps/web/src/main.tsx`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/main.tsx) | React application bootstrap and TanStack Query configuration |
| [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) | Drizzle ORM schema definitions |
| `packages/libs` | Generated TypeScript API client consumed by the web UI |
| `packages/permissions` | Canonical permission and role definitions |

## Verifying Your Setup

Confirm successful installation by checking these endpoints:

1. **API health**: `curl http://localhost:1337/health` (or equivalent health endpoint)
2. **Web UI**: Open `http://localhost:5173` in your browser
3. **Realtime connection**: WebSocket functionality is available through the API's event system

## Troubleshooting Common Issues

**Database connection failures**: Verify `DATABASE_URL` matches your running PostgreSQL instance. The Docker Compose setup handles this automatically.

**Port conflicts**: The default ports are `1337` (API) and `5173` (web). Change these in `.env` if occupied.

**Missing dependencies**: Run `pnpm install` from the repository root, not individual package directories.

## Summary

- **Kaneo local development** requires a single `.env` file at the repository root shared by all packages
- **`pnpm dev`** starts both API ([`apps/api/src/openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/openapi.ts)) and web ([`apps/web/src/main.tsx`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/main.tsx)) with hot-reload
- **Docker Compose** ([`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml)) provides PostgreSQL and Kaneo in one command for fastest setup
- **Shared libraries** (`packages/libs`) automatically generate typed clients for type-safe API consumption
- Source configuration references [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) for complete environment variable documentation

## Frequently Asked Questions

### What Node.js version does Kaneo require?

Kaneo targets current LTS Node.js versions. Check [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) engines or the repository README for exact version constraints. The pnpm workspace generally handles version consistency across the monorepo.

### Can I use npm or yarn instead of pnpm?

No—Kaneo relies on pnpm workspace features for monorepo dependency resolution and script orchestration. The `pnpm dev` command specifically depends on pnpm's workspace filtering to run multiple packages in parallel.

### Where does the database schema live?

The Drizzle ORM schema is defined in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) with relations in [`apps/api/src/database/relations.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/relations.ts). Migrations and schema changes should be made through these files according to the database tooling configured in the API package.

### How do I add custom environment variables?

Add variables to the root `.env` file and reference them through the application code. The API layer in `apps/api` consumes these via standard environment access, while the web layer receives them through the build process. Document any additions in [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) for team consistency.