Kaneo Example Usage Scenarios: 4 Deployment Methods Explained

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, this deployment is positioned as the zero-friction entry point:

# 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#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

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

# 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) 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

# 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 documents production patterns including TLS termination and custom domains:

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#L32-L61) describes both interactive and automated installation:

# 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:

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

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