# How to Set Up the Kaneo API Locally: Complete Development Guide

> Easily set up the Kaneo API locally with Node.js, pnpm, and PostgreSQL. Follow our complete guide to configure your environment and run the Hono-based API in minutes.

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

---

**To set up the Kaneo API locally, install Node.js 20 and pnpm, configure your `.env` file with `KANEO_API_URL`, `KANEO_CLIENT_URL`, and a 32-character `AUTH_SECRET`, start PostgreSQL via Docker or locally, and run `pnpm dev` from the monorepo root to launch the Hono-based API on port 1337.**

Kaneo is an open-source project management platform built on a modern TypeScript stack. The backend API is a **Hono** application that uses **Better-Auth** for authentication, **Drizzle-ORM** for database operations, and **PostgreSQL** as the data store. When you set up the Kaneo API locally, it runs on port `1337` by default and shares a single `.env` file with the React frontend.

## Prerequisites

Before cloning the repository, ensure your system meets these requirements:

- **Node.js 20** or higher
- **pnpm** for package management
- **Git** for version control
- **PostgreSQL** (local installation or Docker)

The monorepo structure is documented in [`AGENTS.md`](https://github.com/usekaneo/kaneo/blob/main/AGENTS.md), with the API source located under `apps/api`.

## Clone and Install Dependencies

Start by cloning the repository and installing workspace dependencies:

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

```

This command installs all packages across the monorepo workspaces, including the API dependencies defined in [`apps/api/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/api/package.json).

## Configure Environment Variables

The API requires several environment variables to function correctly. Copy the sample file and customize it for your local setup:

```bash
cp .env.sample .env

```

Edit the `.env` file with these required variables:

- `KANEO_CLIENT_URL` — URL of the React frontend for redirects (default: `http://localhost:5173`)
- `KANEO_API_URL` — Base URL of the API used by Better-Auth (default: `http://localhost:1337`)
- `AUTH_SECRET` — A 32-byte minimum secret for JWT signing (generate with `openssl rand -hex 32`)
- `DATABASE_URL` — PostgreSQL connection string (e.g., `postgresql://kaneo:kaneo@localhost:5432/kaneo`)

In [`apps/api/src/auth.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/auth.ts) (lines 83-94), the API defaults `KANEO_API_URL` to `http://localhost:1337` and `KANEO_CLIENT_URL` to `http://localhost:5173` if not specified. The same file validates the `AUTH_SECRET` length on lines 104-108, aborting startup if the secret is shorter than 32 characters.

Optional variables include `CORS_ORIGINS` for development (leave empty to allow all origins) and individual `POSTGRES_*` variables if you prefer constructing the connection string from parts rather than using `DATABASE_URL`.

## Set Up PostgreSQL

You can run PostgreSQL via Docker Compose (recommended) or use a local installation.

### Docker Compose Method

Create a [`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml) file in the project root:

```yaml
services:
  postgres:
    image: postgres:16-alpine
    env_file: .env
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kaneo"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

```

Start the database:

```bash
docker compose up -d postgres

```

### Local PostgreSQL Method

If you have PostgreSQL installed locally:

```bash
createdb kaneo
psql -U postgres -d kaneo -c "CREATE USER kaneo WITH PASSWORD 'kaneo';"
psql -U postgres -d kaneo -c "GRANT ALL PRIVILEGES ON DATABASE kaneo TO kaneo;"

```

Update `DATABASE_URL` in your `.env` file to match your local credentials.

## Start the Development Server

To run both the API and the web frontend simultaneously, use the workspace root command:

```bash
pnpm dev

```

This executes the dev script defined in the root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json), which concurrently starts `apps/api` on port 1337 and `apps/web` on port 5173.

To run only the API server:

```bash
cd apps/api
pnpm dev

```

This launches the Hono server using `vite-node`, enabling hot module replacement for the TypeScript source files in [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts).

## Verify the Installation

Test that the API is responding correctly:

```bash
curl http://localhost:1337/config

```

A successful response returns JSON containing the current configuration values including `clientUrl` and `apiUrl`.

You can also access the auto-generated OpenAPI specification at `http://localhost:1337/openapi.json`. The OpenAPI plugin is registered in [`apps/api/src/auth.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/auth.ts) (line 555) and automatically serves the API documentation based on your Hono routes.

## Summary

- **Install** Node.js 20 and pnpm, then clone `usekaneo/kaneo` and run `pnpm install`
- **Configure** the `.env` file with `KANEO_API_URL`, `KANEO_CLIENT_URL`, and a 32+ character `AUTH_SECRET` (validated in [`apps/api/src/auth.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/auth.ts))
- **Database** can run via Docker Compose or local PostgreSQL; connection string goes in `DATABASE_URL`
- **Launch** the full stack with `pnpm dev` or the API alone with `cd apps/api && pnpm dev`
- **Verify** by calling `GET /config` or checking the OpenAPI docs at [`/openapi.json`](https://github.com/usekaneo/kaneo/blob/main//openapi.json)

## Frequently Asked Questions

### What are the minimum requirements for the AUTH_SECRET?

The `AUTH_SECRET` must be at least 32 characters long. According to [`apps/api/src/auth.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/auth.ts) (lines 104-108), the API performs strict validation at startup and exits with an error if the secret is too short. Generate a secure value using `openssl rand -hex 32`.

### Can I run the Kaneo API without Docker?

Yes. While Docker Compose simplifies PostgreSQL setup, you can run the API with a locally installed PostgreSQL instance. Install PostgreSQL 14 or higher, create the database and user manually, update `DATABASE_URL` in your `.env` file accordingly, and run `pnpm dev` from the repository root.

### How do I change the default API port from 1337?

Set the `KANEO_API_URL` environment variable to your desired URL including the port (e.g., `http://localhost:3000`). The API reads this value in [`apps/api/src/auth.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/auth.ts) to configure the Better-Auth `baseURL`. Ensure you also update `VITE_API_URL` in the frontend `.env` or the root `.env` so the web application knows where to send requests.

### What database schema does Kaneo use?

Kaneo uses **Drizzle-ORM** with a schema defined in [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts). This file contains table definitions for users, workspaces, projects, tasks, sessions, and other entities. The API uses this schema to generate and run migrations against your PostgreSQL database automatically on startup.