# How to Set Up a Development Environment for the Kaneo Project: A Complete Guide

> Set up your usekaneo/kaneo development environment quickly. Clone the repo, install dependencies, configure .env, and run pnpm dev to launch the API and web UI.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: getting-started
- Published: 2026-08-04

---

**Clone the `usekaneo/kaneo` repository, install pnpm dependencies, configure a root `.env` file, and run `pnpm dev` to start the API on port 1337 and the web UI on port 5173.**

Setting up a development environment for Kaneo—the self-hosted project management platform—requires understanding its **pnpm monorepo** architecture managed by **TurboRepo**. Both the API and web applications share a single `.env` configuration at the repository root, streamlining local development.

## Prerequisites

Before you begin, ensure you have the following installed:

- **Node.js 18+** (required for the Hono-based API)
- **pnpm 10+** (the project's designated package manager)
- **PostgreSQL** (or use the provided Docker Compose setup)

Kaneo uses a modern, unified stack: the API layer runs on **Hono** with **Drizzle ORM**, while the frontend uses **React 19+**, **Vite**, **TanStack Router**, and **Tailwind v4**.

## Step 1: Clone the Repository

Start by cloning the Kaneo repository from GitHub:

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

```

The project structure follows a standard TurboRepo layout with two main applications under `apps/`:

| Component | Location | Technology |
|-----------|----------|------------|
| API | `apps/api/` | Hono, Node 18, Drizzle ORM, Better Auth, Valibot |
| Web | `apps/web/` | React 19+, Vite, TanStack Router & Query, Tailwind v4, Zustand |

## Step 2: Install Dependencies

Install all packages using pnpm. This command installs dependencies across the entire monorepo, including shared packages:

```bash
pnpm install

```

As noted in the [[`README.md`](https://github.com/usekaneo/kaneo/blob/main/README.md)](https://github.com/usekaneo/kaneo/blob/main/README.md#L55), pnpm is the required package manager for this project.

## Step 3: Configure Environment Variables

Create a `.env` file in the **repository root**. Both the API and web applications read from this single location, as documented in [[`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md)](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md#L18-L34).

Copy the sample file and set the minimum required variables:

```bash
cp .env.sample .env

```

Fill in your `.env` with these essential values:

```dotenv

# .env

KANEO_CLIENT_URL=http://localhost:5173
KANEO_API_URL=http://localhost:1337
AUTH_SECRET=$(openssl rand -hex 32)   # Must be ≥ 32 characters

DATABASE_URL=postgresql://kaneo:password@localhost:5432/kaneo
POSTGRES_DB=kaneo
POSTGRES_USER=kaneo
POSTGRES_PASSWORD=password

```

**Critical requirements:**

- **AUTH_SECRET** must be at least 32 characters—use `openssl rand -hex 32` to generate a cryptographically secure value
- **DATABASE_URL** must match your local PostgreSQL instance or Docker setup

For the complete list of available variables and troubleshooting guidance, refer to the [environment setup guide](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md).

## Step 4: Start the Development Servers

Launch both applications simultaneously with TurboRepo's watch mode:

```bash
pnpm dev

```

This command, referenced in the [README quick-start section](https://github.com/usekaneo/kaneo/blob/main/README.md#L131-L142), starts:

- **API server** on `http://localhost:1337`
- **Web application** on `http://localhost:5173` with hot module replacement

The web UI automatically connects to the API using the `KANEO_API_URL` variable from your `.env` file.

## Alternative: Docker Compose Setup

For containerized development, Kaneo provides a [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) that includes PostgreSQL and the application container:

```bash

# After configuring .env

docker compose up -d

```

The Docker Compose configuration exposes the web UI at `http://localhost:5173` and handles database initialization automatically. See the [compose example in the README](https://github.com/usekaneo/kaneo/blob/main/README.md#L70-L102) for additional options.

Full [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) excerpt:

```yaml
services:
  postgres:
    image: postgres:16-alpine
    env_file: [.env]
  kaneo:
    image: ghcr.io/usekaneo/kaneo:latest
    ports: ["5173:5173"]
    env_file: [.env]
    depends_on:
      postgres:
        condition: service_healthy

```

## Key Configuration Files

Understanding these files accelerates troubleshooting and customization:

| File | Purpose | Location |
|------|---------|----------|
| `.env.sample` | Template for all environment variables | Repository root |
| [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) | Detailed variable documentation and troubleshooting | Repository root |
| [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) | Docker Compose orchestration | Repository root |
| [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) | Drizzle ORM table definitions | [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts) |
| `apps/web/src/hooks/queries/` | Frontend data fetching with TanStack Query | `apps/web/src/hooks/queries/` |
| `apps/web/src/fetchers/` | API client helpers | `apps/web/src/fetchers/` |

## Summary

- **Kaneo uses a pnpm monorepo** with TurboRepo to coordinate the API and web applications
- **Single `.env` configuration** at the repository root serves both services—no per-app configuration needed
- **Minimum requirements**: `KANEO_CLIENT_URL`, `KANEO_API_URL`, `AUTH_SECRET` (≥32 chars), and `DATABASE_URL`
- **`pnpm dev`** launches both development servers with automatic reloading
- **Docker Compose alternative** handles PostgreSQL and application startup in containers

## Frequently Asked Questions

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

Kaneo's API is built on **Hono** and requires **Node.js 18 or newer**, as specified in the API's tech stack. The web application uses **React 19+** and **Vite**, which also benefit from recent Node versions.

### Why is my authentication failing with "Invalid secret"?

Your `AUTH_SECRET` environment variable is either missing or shorter than **32 characters**. Generate a valid secret with `openssl rand -hex 32` and ensure it's set in your root `.env` file. Both the API and authentication layer (Better Auth) enforce this minimum length.

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

No. Kaneo's monorepo configuration—including workspace definitions and TurboRepo pipelines—is **specific to pnpm**. The lockfile and dependency resolution expect pnpm v10, so using alternative package managers will cause installation failures.

### How do I add new database tables to Kaneo?

Database schema changes are managed through **Drizzle ORM** in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts). After modifying the schema, run the DrizzleKit generate and migrate commands (typically wrapped in pnpm scripts) to apply changes to your PostgreSQL instance.