Architecture

Kohakku has four layers:

Controller (Django)

Orchestration brain — manages tasks, skills, configs, workflows, tenancy. Serves the operator UI and API.

Dispatcher (Go)

Execution engine — consumes the task queue, spawns containers, monitors lifecycle, handles agent check-in/check-back, fires callbacks.

Runtime Backend

Pluggable infrastructure layer behind the Dispatcher:

Backend	Config	Use Case
local	Docker socket	Development, single-machine
k8s	Kubeconfig	Production Kubernetes
ecs	AWS credentials	Production AWS Fargate
worker	None	Lightweight subprocess tasks

Agent Sandbox

The container image the agent runs inside. Seven tiers from CLI-only (basic) to full desktop with VNC (desktop). Four runtimes per tier: claude, codex, gemini, all.

Data Flow

1. Operator creates task (or workflow dispatches one)
2. Controller assembles brief (skills + configs + instructions)
3. Controller uploads brief to object storage
4. Controller POSTs task to Dispatcher (or publishes to queue)
5. Dispatcher dequeues, spawns container via runtime backend
6. Agent boots, downloads brief, activates runtime
7. Agent checks in with Dispatcher
8. Agent does work, reports progress
9. Agent checks back with result
10. Dispatcher fires callback to Controller
11. Controller updates task record, signals workflow if applicable