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

> Learn how to set up the Kaneo API locally with this developer guide. Clone the repository, configure environment variables, and run pnpm dev to launch the Hono API on port 1337.

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

---

**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`](https://github.com/usekaneo/kaneo/blob/main/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:

```bash
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:

```bash
pnpm install

```

### Configure Environment Variables

Create a local environment file by copying the example template:

```bash
cp .env.example .env

```

Edit `.env` to include the four required variables for local development. According to the [ENVIRONMENT_SETUP.md](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md#L24-L33), you must set:

```dotenv
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)](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)](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:

```bash
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:

```bash
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)](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)](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:

```bash
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)](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:

```bash
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](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md#L24-L33).
- **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)](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)](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:

```bash
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)](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)](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.