Kanchi Logo Kanchi
Getting Started

Installation

Deploy Kanchi for production with Docker, or run it locally for development.

Kanchi runs wherever Docker runs. For production, point it at PostgreSQL. For development, SQLite works great.

Kanchi doesn't manage your message broker or database infrastructure. You bring RabbitMQ or Redis, and optionally PostgreSQL. We handle the monitoring.

Installation methods

Docker Compose

Production deployment modeled after Docmost — simple and reliable.

Local Development

Run from source for development and contributions.

Docker Only

Single-container deployment for minimal setups.

Docker Compose

The recommended deployment method. Create a compose file, set your broker URL, run one command.

Create docker-compose.yaml

Save the following as docker-compose.yaml:

services:
  kanchi:
    image: getkanchi/kanchi:latest
    container_name: kanchi
    ports:
      - "3000:3000"
      - "8765:8765"
    environment:
      # Required: Your broker URL
      CELERY_BROKER_URL: ${CELERY_BROKER_URL}

      # Optional: Database (defaults to SQLite)
      DATABASE_URL: ${DATABASE_URL:-sqlite:////data/kanchi.db}

      # Optional: Frontend URLs
      NUXT_PUBLIC_API_URL: ${NUXT_PUBLIC_API_URL:-http://localhost:8765}
      NUXT_PUBLIC_WS_URL: ${NUXT_PUBLIC_WS_URL:-ws://localhost:8765/ws}
    volumes:
      - kanchi-data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8765/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  kanchi-data:
services:
  kanchi:
    image: getkanchi/kanchi:latest
    container_name: kanchi
    ports:
      - "3000:3000"
      - "8765:8765"
    environment:
      CELERY_BROKER_URL: ${CELERY_BROKER_URL}
      DATABASE_URL: postgresql+asyncpg://kanchi:kanchi@postgres:5432/kanchi

      # Optional: Secrets (recommended for production)
      SESSION_SECRET_KEY: ${SESSION_SECRET_KEY}
      TOKEN_SECRET_KEY: ${TOKEN_SECRET_KEY}

      # Optional: Authentication
      AUTH_ENABLED: ${AUTH_ENABLED:-false}
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: kanchi
      POSTGRES_PASSWORD: kanchi
      POSTGRES_DB: kanchi
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kanchi"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  postgres_data:
services:
  kanchi:
    image: getkanchi/kanchi:latest
    container_name: kanchi
    ports:
      - "3000:3000"
      - "8765:8765"
    environment:
      # Point to your existing infrastructure
      CELERY_BROKER_URL: ${CELERY_BROKER_URL}
      DATABASE_URL: ${DATABASE_URL}

      # Frontend URLs (adjust to your domain)
      NUXT_PUBLIC_API_URL: ${NUXT_PUBLIC_API_URL:-https://your-domain.com}
      NUXT_PUBLIC_WS_URL: ${NUXT_PUBLIC_WS_URL:-wss://your-domain.com/ws}

      # CORS
      ALLOWED_ORIGINS: ${ALLOWED_ORIGINS}
      ALLOWED_HOSTS: ${ALLOWED_HOSTS}

      # Secrets
      SESSION_SECRET_KEY: ${SESSION_SECRET_KEY}
      TOKEN_SECRET_KEY: ${TOKEN_SECRET_KEY}
    restart: unless-stopped

Set required environment variables

At minimum, export CELERY_BROKER_URL or add it to a .env file:

# For RabbitMQ:
export CELERY_BROKER_URL=amqp://user:pass@rabbitmq-host:5672//

# For Redis:
export CELERY_BROKER_URL=redis://localhost:6379/0

Optional overrides:

# Database (if not using SQLite)
export DATABASE_URL=postgresql://user:pass@postgres-host:5432/kanchi

# Secrets (recommended for production)
export SESSION_SECRET_KEY=$(openssl rand -hex 32)
export TOKEN_SECRET_KEY=$(openssl rand -hex 32)

Start Kanchi

docker compose up -d --pull always

The same command handles both initial deployment and updates. Re-run to pull the latest image and restart.

Access the dashboard

Open http://localhost:3000

Backend API documentation: http://localhost:8765/docs

Database migrations run automatically on startup. No manual Alembic commands needed.

Local Development

Run Kanchi from source for development or contributions.

Install prerequisites

  • Python 3.8+ with Poetry
  • Node.js 20+ with npm
  • A running message broker (RabbitMQ or Redis)
# macOS with Homebrew
brew install python poetry node rabbitmq

# Start RabbitMQ
brew services start rabbitmq

Clone and install dependencies

git clone https://github.com/getkanchi/kanchi.git
cd kanchi

# Backend dependencies
cd agent
poetry install

# Frontend dependencies
cd ../frontend
npm install

Configure environment

From the project root, create a .env file or export variables:

# Required: broker connection
export CELERY_BROKER_URL=amqp://guest:guest@localhost:5672//

# Optional: database (defaults to SQLite in project directory)
export DATABASE_URL=sqlite:///kanchi.db

# Optional: API URLs for frontend
export NUXT_PUBLIC_API_URL=http://localhost:8765
export NUXT_PUBLIC_WS_URL=ws://localhost:8765/ws

# Optional: development mode (enables debug logging)
export DEVELOPMENT_MODE=true
export LOG_LEVEL=DEBUG

Start the application

From the project root:

make dev

This starts:

Or run separately:

# Terminal 1: Backend
cd agent
poetry run python app.py

# Terminal 2: Frontend
cd frontend
npm run dev

Development commands

# View unified logs
make logs

# Seed database with demo data
make seed

# Backend only
make backend

# Frontend only
make frontend

# Format backend code
cd agent && poetry run black .

# Lint backend code
cd agent && poetry run ruff check .

# Type-safe API client generation (from backend OpenAPI schema)
cd frontend && npm run generate:api

Docker Only

Single-container deployment for minimal setups. Requires an external broker and database.

docker run -d \
  --name kanchi \
  -p 3000:3000 \
  -p 8765:8765 \
  -e CELERY_BROKER_URL=amqp://user:pass@rabbit-host:5672// \
  -e DATABASE_URL=postgresql+asyncpg://user:pass@pg-host:5432/kanchi \
  -e SESSION_SECRET_KEY=$(openssl rand -hex 32) \
  -e NUXT_PUBLIC_API_URL=http://localhost:8765 \
  -e NUXT_PUBLIC_WS_URL=ws://localhost:8765/ws \
  getkanchi/kanchi:latest

For SQLite (development only):

docker run -d \
  --name kanchi \
  -p 3000:3000 \
  -p 8765:8765 \
  -v kanchi-data:/data \
  -e CELERY_BROKER_URL=redis://redis-host:6379/0 \
  -e DATABASE_URL=sqlite:////data/kanchi.db \
  getkanchi/kanchi:latest

Verify installation

After deploying Kanchi:

Check backend health

curl http://localhost:8765/api/health

You should get a 200 OK response.

View logs

docker compose logs -f kanchi
docker logs -f kanchi
tail -f kanchi.log

Look for: Connected to broker in the logs.

Run a test task

Execute a task from your Celery application. It should appear in the Kanchi dashboard within seconds.

If tasks don't appear, ensure your Celery workers have events enabled:

# In your Celery config
worker_send_task_events = True
task_send_sent_event = True

Or start workers with the -E flag:

celery -A your_app worker -E

Troubleshooting

Next steps

Quickstart

Learn the basics with a 5-minute tutorial.

Configuration

Explore all environment variables and options.

Production Deployment

Best practices for production deployments.

Authentication

Secure your Kanchi instance with authentication.

Quickstart

Run Kanchi locally in under 5 minutes.

Architecture

Understanding how Kanchi works under the hood

On this page

Installation methodsDocker ComposeLocal DevelopmentDevelopment commandsDocker OnlyVerify installationTroubleshootingNext steps