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

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, with the API source located under apps/api.

Clone and Install Dependencies

Start by cloning the repository and installing workspace dependencies:

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.

Configure Environment Variables

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

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 (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 file in the project root:

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:

docker compose up -d postgres

Local PostgreSQL Method

If you have PostgreSQL installed locally:

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:

pnpm dev

This executes the dev script defined in the root package.json, which concurrently starts apps/api on port 1337 and apps/web on port 5173.

To run only the API server:

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.

Verify the Installation

Test that the API is responding correctly:

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 (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)
• 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

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

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