# How to Set Up Kaneo Locally: Complete Development Environment Guide

> Set up Kaneo locally with this complete guide. Learn how to install Node.js, configure your .env file, and run the development environment using pnpm dev for API and web app.

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

---

**Kaneo is a pnpm monorepo using TurboRepo that requires Node.js ≥18, a single `.env` file in the repository root, and the `pnpm dev` command to run both the API (port 1337) and web app (port 5173) simultaneously.**

According to the `usekaneo/kaneo` source code, this project management platform is organized as a **pnpm monorepo** containing a Hono-based API and a React 19 frontend. Setting up Kaneo locally involves cloning the repository, installing dependencies with pnpm, and configuring a unified `.env` file that both services share.

## Prerequisites

Before you begin, ensure your system meets the following requirements:

- **Node.js ≥18** – Required for the build toolchain and React 19 features.
- **pnpm** – The mandatory package manager; npm and yarn are not supported.
- **PostgreSQL** – A running instance accessible via connection string, or Docker for the compose alternative.

## Step-by-Step Local Setup

### Clone the Repository

Start by cloning the official repository and entering the project directory:

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

```

### Install Dependencies

Run pnpm install to fetch dependencies for all packages in the monorepo, including `apps/api`, `apps/web`, and shared libraries under `packages/*`:

```bash
pnpm install

```

### Configure Environment Variables

Kaneo uses a single `.env` file in the repository root as the source of truth for all configuration. Copy the sample file:

```bash
cp .env.sample .env

```

Edit `.env` to set these required variables:

- `KANEO_CLIENT_URL` – Frontend origin, typically `http://localhost:5173`
- `KANEO_API_URL` – Backend origin, typically `http://localhost:1337`
- `AUTH_SECRET` – Random 32-character hex string (generate with `openssl rand -hex 32`)
- `DATABASE_URL` – Full PostgreSQL connection string, or individual `POSTGRES_DB`, `POSTGRES_USER`, and `POSTGRES_PASSWORD` values

Example configuration:

```bash
cat <<EOF > .env
KANEO_CLIENT_URL=http://localhost:5173
KANEO_API_URL=http://localhost:1337
AUTH_SECRET=$(openssl rand -hex 32)
DATABASE_URL=postgres://kaneo:password@localhost:5432/kaneo
POSTGRES_DB=kaneo
POSTGRES_USER=kaneo
POSTGRES_PASSWORD=password
EOF

```

For optional features like Redis, SMTP, and SSO, consult the [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md) file in the repository root.

### Start Development Servers

Launch both the API and web applications with hot-reload using TurboRepo:

```bash
pnpm dev

```

This starts the **API on port 1337** and the **web UI on port 5173**. The frontend automatically communicates with the backend via the URLs defined in your `.env` file.

## Docker Compose Alternative

For a containerized sandbox that requires no local Node.js installation, use the provided [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml). This configuration runs PostgreSQL and the official Kaneo image together:

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

```

Execute the stack:

```bash
docker compose up -d

```

Once containers are healthy, access Kaneo at **http://localhost:5173**.

## Understanding the Monorepo Structure

Familiarity with the codebase layout helps when running targeted commands:

- **`apps/api/`** – Backend built with Hono, Drizzle ORM, Better Auth, and Valibot. Contains database migrations in `apps/api/drizzle/`.
- **`apps/web/`** – Frontend built with React 19+, Vite, Tailwind v4, TanStack Router, and Zustand.
- **`packages/*/`** – Shared libraries including [`packages/libs/src/api-url.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/api-url.ts), which constructs API URLs from environment variables for isomorphic usage.

The single `.env` file approach ensures consistent configuration across the API and web layers, as both services read from the same source of truth.

## Database Migrations

As implemented in `usekaneo/kaneo`, Drizzle migrations stored under `apps/api/drizzle` apply automatically when the API starts. To generate new migrations after schema changes:

```bash
pnpm --filter @kaneo/api db:generate

```

## Summary

- **Prerequisites**: Node.js ≥18, pnpm, and PostgreSQL (or Docker).
- **Configuration**: Copy `.env.sample` to `.env` and set `KANEO_CLIENT_URL`, `KANEO_API_URL`, `AUTH_SECRET`, and database credentials.
- **Development**: Run `pnpm dev` to start both API (port 1337) and web (port 5173) with hot-reload.
- **Docker**: Use `docker compose up -d` for a one-command sandbox environment.
- **Architecture**: Shared `.env` file and TurboRepo coordinate the Hono backend and React frontend.

## Frequently Asked Questions

### What Node.js version is required to set up Kaneo locally?

Kaneo requires **Node.js version 18 or higher** to support the modern build toolchain and React 19 features used throughout the monorepo. Attempting to run `pnpm install` or `pnpm dev` with earlier versions will result in compatibility errors.

### Why is the Kaneo API failing to connect to PostgreSQL?

Verify that your `.env` file contains a valid `DATABASE_URL` or the separate `POSTGRES_*` variables, and ensure PostgreSQL is accessible from your host. When using Docker Compose, the `depends_on` condition ensures the database is healthy before the Kaneo container starts, preventing connection race conditions.

### Can I run Kaneo locally without using Docker?

Yes. The standard local development workflow uses pnpm and Node.js directly. Simply clone the repository, run `pnpm install`, configure your `.env` file to point to a local or remote PostgreSQL instance, and execute `pnpm dev`. Docker is only required if you prefer containerized services.

### How do I create new database migrations in the Kaneo API?

After modifying schema definitions in [`apps/api/src/db/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/db/schema.ts) (or relevant files), run `pnpm --filter @kaneo/api db:generate` from the repository root. This creates new migration files under `apps/api/drizzle` that apply automatically on the next API startup.