KanchiQuickstart
Run Kanchi locally in under 5 minutes.
Get Kanchi running alongside your Celery workers in minutes. This guide assumes you already have a message broker (RabbitMQ or Redis) running.
Prerequisites: You need a running message broker that your Celery workers are connected to. Kanchi monitors task events from this broker — it doesn't manage broker infrastructure for you.
Quick start with Docker
The fastest way to run Kanchi is with Docker. No repository cloning required—just create a compose file and start the container.
Create a docker-compose.yaml file
Create a new directory and save the following as docker-compose.yaml:
services:
kanchi:
image: getkanchi/kanchi:latest
container_name: kanchi
ports:
- "3000:3000"
- "8765:8765"
environment:
# Required: Your Celery broker connection string
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:Set your broker connection
Export CELERY_BROKER_URL or place it in a .env file:
export CELERY_BROKER_URL=amqp://user:pass@rabbitmq-host:5672//export CELERY_BROKER_URL=redis://localhost:6379/0Or create a .env file alongside docker-compose.yaml:
CELERY_BROKER_URL=amqp://user:pass@rabbitmq-host:5672//Start Kanchi
docker compose up -d --pull alwaysThis pulls the latest image from Docker Hub and starts the container. Access the dashboard at http://localhost:3000
Verify the connection
Check the logs to confirm Kanchi connected to your broker:
docker compose logs -f kanchiYou should see: Connected to broker in the output.
The same command handles both initial deployment and updates. Just re-run docker compose up -d --pull always to update.
Local development setup
If you're developing Kanchi or want to run it without Docker:
Install dependencies
You'll need:
- Python 3.8+ with Poetry
- Node.js 20+ with npm
- A running message broker (RabbitMQ or Redis)
# Clone the repository
git clone https://github.com/getkanchi/kanchi.git
cd kanchi
# Backend dependencies
cd agent
poetry install
# Frontend dependencies
cd ../frontend
npm installConfigure environment variables
Create a .env file or export variables:
# Required: broker connection
export CELERY_BROKER_URL=amqp://guest:guest@localhost:5672//
# Optional: database (defaults to SQLite)
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/wsStart the application
From the project root:
make devThis starts both the FastAPI backend (port 8765) and Nuxt frontend (port 3000).
Access the dashboard
Open http://localhost:3000 in your browser.
Generate test tasks
If you want to see Kanchi in action without a production workload, use the included test environment:
cd scripts/test-celery-app
# Start RabbitMQ, Redis, and test Celery workers
make start
# Generate mixed task load (success, failures, retries)
make test-mixed
# Generate only successful tasks
make test-success
# Generate only failing tasks
make test-failure
# Stop test environment
make stopTasks will appear in the Kanchi dashboard in real-time as they execute.
Verify your setup
Check backend health
curl http://localhost:8765/api/healthYou should get a 200 OK response.
Verify broker connection
Check application logs for "Connected to broker" messages:
tail -f kanchi.logdocker compose logs -f kanchiRun a test task
Execute a task from your Celery application. It should appear in the Kanchi dashboard within seconds.
Troubleshooting
Next steps
Now that Kanchi is running, explore the core features: