Skip to content

Quick Start

Get the full Kohakku stack running locally and dispatch your first agent task.

Prerequisites

  • Docker and Docker Compose v2+
  • 4 GB+ RAM (8 GB recommended)
  • Ports 8000, 8080, 5432, 6379, 9000, 9001, 7233, 8088 available

Optional (for K8s runtime):

brew install k3d

1. Clone and Start

git clone git@github.com:ConflictHQ/kohakku.git
cd kohakku
make setup   # creates .env files from examples
make up      # starts all services
make migrate # runs Django migrations
make seed    # seeds demo data

Wait for all services to become healthy:

make ps

2. Verify the Stack

URL Service
http://localhost:8000 Controller (workflow UI, admin)
http://localhost:8000/admin Django admin
http://localhost:8080 Dispatcher (operator gallery, task API)
http://localhost:8088 Temporal UI
http://localhost:9001 MinIO console (minioadmin / minioadmin)

Check health endpoints:

curl -s http://localhost:8000/health/ | python -m json.tool
curl -s http://localhost:8080/health  | jq .

3. Get an API Token

docker compose exec -T controller python manage.py shell -c "
from django.contrib.auth.models import User
from rest_framework.authtoken.models import Token
user = User.objects.get(username='admin')
token, _ = Token.objects.get_or_create(user=user)
print(token.key)
"

Save the token -- you will use it in subsequent API calls.

4. Create a Skill

curl -X POST http://localhost:8000/api/v1/skills/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token YOUR_TOKEN" \
  -d '{
    "name": "hello-world",
    "category": "tool",
    "description": "A minimal greeting skill.",
    "instructions": "Respond with a friendly greeting. Include the current date."
  }'

5. Dispatch a Task

The seed data creates a default AgentDefinition and RuntimeTarget. Dispatch a task using the Controller UI at http://localhost:8000 or via the API.

Via the Controller UI

  1. Navigate to http://localhost:8000
  2. Click New Task
  3. Select the agent definition and attach the hello-world skill
  4. Click Dispatch

Via the API

# The seed creates default records — check them first
curl -s http://localhost:8000/api/v1/tasks/ \
  -H "Authorization: Token YOUR_TOKEN" | python -m json.tool

6. Monitor the Task

Open http://localhost:8080 -- running agents appear as tiles with status, duration, and (for visual tiers) a noVNC link.

Temporal UI

Open http://localhost:8088 -- workflow executions show status, signal delivery, and activity history.

Poll Task Status

curl -s http://localhost:8080/tasks/{task_id} \
  -H "X-API-Key: $(grep DISPATCH_API_KEY controller/.env | cut -d= -f2)" | jq .

7. (Optional) Set Up k3d Runtime

For K8s-based agent execution instead of local Docker:

# Create local cluster with registry
make k3d-up

# Build and push an agent image
make agent-build TIER=basic RUNTIME=claude
make agent-push TIER=basic RUNTIME=claude REGISTRY=localhost:5000

# Verify
kubectl get nodes --context k3d-kohakku

Update the Dispatcher's .env to use the K8s backend:

RUNTIME_BACKEND=k8s

Then restart the dispatcher:

docker compose restart dispatcher

Next Steps