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

Clone the usekaneo/kaneo repository, install pnpm dependencies, copy .env.example to .env and configure DATABASE_URL, AUTH_SECRET, KANEO_API_URL, and KANEO_CLIENT_URL, start PostgreSQL, then run pnpm dev to launch the Hono-based API on port 1337.

Setting up the Kaneo API locally requires a Node.js environment with pnpm and PostgreSQL. The monorepo structure houses both the API (apps/api) and the web frontend in a single codebase that shares a root-level .env file for configuration.

Prerequisites

Before installing, ensure your system has:

• Node.js 18+ and pnpm (required by the root package.json)
• PostgreSQL 16+ (local installation or Docker)
• Git for cloning the repository

Step-by-Step Installation

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

The project uses pnpm workspaces to manage the monorepo. Install all dependencies from the root:

pnpm install

Configure Environment Variables

Create a local environment file by copying the example template:

cp .env.example .env

Edit .env to include the four required variables for local development. According to the ENVIRONMENT_SETUP.md, you must set:

KANEO_CLIENT_URL=http://localhost:5173
KANEO_API_URL=http://localhost:1337
AUTH_SECRET=your-random-32-character-hex-string
DATABASE_URL=postgresql://kaneo:password@localhost:5432/kaneo

The AUTH_SECRET is used by the JWT authentication system defined in [apps/api/src/auth.ts](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/auth.ts), while DATABASE_URL connects to the Drizzle ORM schema in [apps/api/src/database/schema.ts](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts).

Start the Database

You can use Docker Compose to run PostgreSQL without a local installation:

docker compose -f compose.yml up -d postgres

Alternatively, ensure your local PostgreSQL instance is running and the database kaneo exists with the credentials matching your DATABASE_URL.

Launch the Development Servers

From the repository root, start both the API and web frontend concurrently:

pnpm dev

This command uses the workspace filter to run the API dev server (port 1337) and the web dev server (port 5173) simultaneously. The API entry point in [apps/api/src/index.ts](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts) bootstraps the Hono application, loads configuration from [apps/api/src/config/index.ts](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/config/index.ts), and automatically applies database migrations on startup.

Verify the Installation

Test that the API is responding by requesting the public configuration endpoint:

curl http://localhost:1337/config

A successful response returns JSON containing clientUrl and apiUrl values, confirming that the server in [apps/api/src/index.ts](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts) is serving requests and reading environment variables correctly.

Docker Compose Alternative

For a one-command setup that bundles the API, web UI, and PostgreSQL, use the pre-configured Compose file:

docker compose up -d

This method uses the official ghcr.io/usekaneo/kaneo:latest image and automatically wires the services together using the environment variables defined in your .env file.

Summary

• Clone the usekaneo/kaneo repository and run pnpm install to initialize the monorepo.
• Configure the .env file with DATABASE_URL, AUTH_SECRET, KANEO_API_URL, and KANEO_CLIENT_URL as specified in ENVIRONMENT_SETUP.md.
• Start PostgreSQL locally or via Docker Compose before launching the application.
• Run pnpm dev to start the API on port 1337 and the web interface on port 5173.
• Verify connectivity by curling the /config endpoint or checking the Drizzle-managed database connection in [apps/api/src/database/schema.ts](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts).

Frequently Asked Questions

What port does the Kaneo API use in local development?

The Kaneo API listens on port 1337 by default when running pnpm dev. This value is controlled by the KANEO_API_URL environment variable set in your .env file, which the configuration loader in [apps/api/src/config/index.ts](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/config/index.ts) reads at startup.

Can I run the Kaneo API without using Docker?

Yes. Install PostgreSQL 16+ locally, create a database and user matching your DATABASE_URL, then run pnpm dev from the repository root. The API will connect directly to your local Postgres instance without requiring any Docker containers.

How do I generate the required AUTH_SECRET for local testing?

Generate a secure 32-character hexadecimal string using OpenSSL or any random generator:

openssl rand -hex 32

Paste this value into the AUTH_SECRET field of your .env file. This secret signs JWT tokens in the authentication flow implemented in [apps/api/src/auth.ts](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/auth.ts).

Does the Kaneo API automatically create database tables?

Yes. When the server starts, it runs Drizzle migrations automatically based on the schema defined in [apps/api/src/database/schema.ts](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts). Ensure your PostgreSQL instance is running before starting the API to allow the migration engine to create the necessary tables.

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