# Kaneo Example Usage Scenarios: 4 Deployment Methods Explained

> Explore Kaneo example usage scenarios with four deployment methods: one-click local install, Docker Compose, Helm charts, and MCP client. Deploy Kaneo easily for any environment.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: example-usage
- Published: 2026-08-04

---

**Yes, `usekaneo/kaneo` provides four official deployment scenarios—one-click local install with `drim`, Docker Compose quick-start, production-ready Helm charts, and an MCP client for API integration.** These examples cover local development, single-machine production, and cloud-native Kubernetes deployments.

Kaneo is an open-source project management platform built as a **pnpm monorepo** with a **Hono-based API** and **React 19+ frontend**. The repository ships with first-class examples that demonstrate how to run the same codebase across any infrastructure. This guide breaks down each scenario with exact commands, configuration files, and source references.

## One-Click Local Install with `drim`

The fastest way to get Kaneo running locally uses `drim`, a minimal CLI that automates Docker provisioning, HTTPS setup, and database initialization.

In the [README](https://github.com/usekaneo/kaneo/blob/main/README.md#L57-L66), this deployment is positioned as the zero-friction entry point:

```bash

# Download and run the drim installer

curl -fsSL https://assets.kaneo.app/install.sh | sh
drim setup

```

The `drim` tool handles environment detection, pulls the correct container images, and starts the stack. Once complete, Kaneo is available at `http://localhost:5173` or a custom domain if configured during setup.

This approach is ideal for **local evaluation** and **non-technical users** who want to avoid manual Docker configuration.

## Docker Compose Quick-Start

For users who prefer explicit control, the [[`compose.yml`](https://github.com/usekaneo/kaneo/blob/main/compose.yml)](https://github.com/usekaneo/kaneo/blob/main/compose.yml#L1-L27) file defines a two-service stack with PostgreSQL and the Kaneo application container.

### Service Architecture

The Compose file declares:

- **`postgres`** — Uses `postgres:16-alpine` with health checks and persistent volume
- **`kaneo`** — Runs `ghcr.io/usekaneo/kaneo:latest` with automatic dependency on database readiness

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

  kaneo:
    image: ghcr.io/usekaneo/kaneo:latest
    ports: ["5173:5173"]
    env_file: [.env]
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:5173/api/health"]
      interval: 30s
      timeout: 5s
      start_period: 60s
      retries: 3

volumes:
  postgres_data:

```

### Launch Commands

```bash

# Copy and edit environment variables

cp .env.sample .env

# Start services in background

docker compose up -d

# Verify and open

open http://localhost:5173

```

The `.env` file (documented in [`ENVIRONMENT_SETUP.md`](https://github.com/usekaneo/kaneo/blob/main/ENVIRONMENT_SETUP.md)) defines runtime configuration including `KANEO_CLIENT_URL`, `KANEO_API_URL`, and `AUTH_SECRET`. This same `.env` pattern supports all deployment scenarios.

## Kubernetes and Helm Chart Deployment

For production environments, the official Helm chart provides autoscaling, Ingress/Gateway API exposure, and PVC-backed persistence.

### Basic Local Installation

```bash

# Install with default values, then port-forward

helm install kaneo oci://ghcr.io/usekaneo/charts/kaneo \
  --namespace kaneo --create-namespace
kubectl port-forward svc/kaneo-kaneo 5173:5173 -n kaneo

```

### Production Configuration with Ingress

The [Helm chart README](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/README.md#L22-L30) documents production patterns including TLS termination and custom domains:

```bash
helm install kaneo oci://ghcr.io/usekaneo/charts/kaneo \
  --namespace kaneo --create-namespace \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set "ingress.hosts[0].host=pm.yourcompany.com"

```

Key configurable values include:

- `gateway.enabled` — Use Kubernetes Gateway API instead of Ingress
- `autoscaling.enabled` — Horizontal Pod Autoscaler for the API
- `postgresql.persistence.size` — Database volume sizing
- `kaneo.env.*` — Inject arbitrary environment variables

This is the recommended path for **team deployments**, **high-availability setups**, and **GitOps workflows**.

## MCP Client and Device-Flow Authentication

Kaneo includes a **Model Context Protocol (MCP) client** in `packages/mcp` that enables programmatic API access with device-code authentication.

### Installation Modes

The [[`packages/mcp/README.md`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/README.md)](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/README.md#L32-L61) describes both interactive and automated installation:

```bash

# Interactive installer (prompts for target IDE/config location)

npx @kaneo/mcp

# Non-interactive install for Cursor

kaneo-mcp install --target cursor-user -y

# Connect to self-hosted instance

kaneo-mcp install --target cursor-user -y --api-url https://kaneo.example.com

```

### API Operations

Once authenticated via device flow, the CLI exposes workspace and task operations:

```bash

# List accessible workspaces

kaneo-mcp list_workspaces

# Create a task programmatically

kaneo-mcp create_task --project myproj --title "Write knowledge-base article"

```

This scenario targets **developer tooling integrations**, **AI assistant connections**, and **CI/CD automation** that interacts with project data.

## How Deployment Scenarios Share Code

All four scenarios run identical application code because Kaneo's architecture externalizes configuration:

| Layer | Technology | Configuration Source |
|-------|-----------|----------------------|
| API (`apps/api`) | Hono + Valibot + Drizzle ORM | Environment variables |
| Frontend (`apps/web`) | React 19 + TanStack Router + Tailwind v4 | Build-time env injection |
| Database | PostgreSQL 16 | `DATABASE_URL` env var |

The monorepo structure (pnpm workspaces + TurboRepo) ensures that `ghcr.io/usekaneo/kaneo:latest` contains the same code whether launched by `drim`, Docker Compose, or Kubernetes. Migration files in `apps/api/src/db/migrations` execute automatically on startup, eliminating manual schema management.

## Summary

- **`drim` one-click install** — Fastest local setup, minimal prerequisites
- **Docker Compose** — Explicit, version-controlled container orchestration for single hosts
- **Helm chart** — Production Kubernetes deployment with scalability and Ingress support
- **MCP client** — Programmatic API access with OAuth2 device-flow authentication

Each scenario is documented with working code in the repository and shares the same environment variable contract defined in `.env.sample`.

## Frequently Asked Questions

### What is the fastest way to try Kaneo locally?

Run the `drim` one-liner: `curl -fsSL https://assets.kaneo.app/install.sh | sh && drim setup`. This provisions Docker containers and starts the application without manual configuration.

### Can I use the same environment variables across all deployment methods?

Yes. The `.env.sample` file defines the canonical variable set used by `drim`, Docker Compose, and Kubernetes. Variables like `AUTH_SECRET`, `KANEO_API_URL`, and `DATABASE_URL` are respected in all contexts.

### Does the Helm chart support database persistence?

Yes. The chart can deploy a PostgreSQL subchart with PVC-backed storage, or connect to an external database via `postgresql.enabled=false` and a custom `DATABASE_URL`.

### What authentication flow does the MCP client use?

The MCP client implements **OAuth2 device authorization grant** (device flow). Users authenticate via a browser link, then the CLI receives a bearer token for subsequent API calls.