How to Set Up Kaneo Locally: Complete Development Environment Guide

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:

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/*:

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:

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:

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 file in the repository root.

Start Development Servers

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

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. This configuration runs PostgreSQL and the official Kaneo image together:

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:

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, 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:

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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}