Track A — Setup and generate

kaboum is a Copier template that generates Kaoohi actors — FastAPI + LangChain microservices with conversations in PostgreSQL, auth caching in Redis, dual LLM support, and a marketplace-ready config. You answer a questionnaire once; the template renders a complete, runnable repository. This page covers prerequisites, the render itself, and the answers that shape everything downstream.

Prerequisites

Tool	Minimum	Why you need it
Copier	9.4.0	Template engine. Pinned by the template’s _min_copier_version — 9.0.0 was claimed in older docs but never exercised and does not install on Python 3.12.
Python	3.11 / 3.12 / 3.13	Runtime for the generated actor (3.12 is the template default)
Docker	20.10+	Container builds and local PostgreSQL/Redis
PostgreSQL	14+	Conversations, messages, stats — the only critical service
Redis	6+	Auth caching and the optional reply queue
git	2.30+	Copier clones the template from a git ref

Install Copier isolated from any project environment:

pipx install copier
# or: pip install copier
# or: uv tool install copier

Generate your actor

Interactive (recommended the first time)

copier copy https://github.com/allcare/kaboum /path/to/my-actor

Copier prompts for each variable with its help text and default. Only two answers have no default:

• project_name — lowercase, ^[a-z][a-z0-9_]{1,30}$. Names your DB tables ({project_name}_conversations, …), Docker image, and log events.
• domain_module — the Python package for your domain code (e.g. booking, email). Reserved names are rejected: mesh, agent, api, core, kaoohi, shared, integrations, middleware, models, storage — they collide with template-owned modules.

Everything else has a sensible default; pressing Enter all the way down produces a valid actor.

Non-interactive (scripts, CI)

copier copy https://github.com/allcare/kaboum /path/to/my-actor \
  --vcs-ref v1.2.0 \
  --data project_name=katask \
  --data domain_module=task \
  --data actor_description="AI Task Manager" \
  --defaults \
  --trust

• --data key=value sets one variable; repeat for each.
• --defaults accepts defaults for everything you did not pass.
• --trust skips Copier’s template-safety confirmation.

If the target directory already exists Copier refuses unless you add --overwrite — prefer regenerating into a fresh path.

Always render from a git ref

Pass the repo URL (as above) or a tag via --vcs-ref, never a moving local checkout. Copier records the template commit it used in the generated .copier-answers.yml as _commit. Rendered from a plain filesystem path, that field is null, your actor forgets which kaboum produced it, and copier update has nothing to diff against. Pin a released tag (--vcs-ref v1.2.0) for reproducible renders; use HEAD only when you are deliberably testing unreleased template changes.

The answers that matter

Full variable reference: ](en/reference/copier-variables/). The tour below groups them the way copier.yml does.

Identity and naming

project_name and domain_module (above) plus derived names you rarely override: actor_display_name, domain_display_name, config_class_name (<DisplayName>Config), agent_class_name (<DisplayName>Agent>), actor_description, and python_version (3.11/3.12/3.13, default 3.12).

Agent framework and intelligence

agent_framework picks the agent base:

• deepagents (default) — create_deep_agent with planning, scoped sub-agents, and a summarization pass. Best for genuinely multi-step actors.
• langchain — a plain create_react_agent. Leaner; all intelligence toggles below are no-ops on this path.

On the deepagents path, three toggles shape the middleware stack — all default on for parity, and each adds tokens or latency per turn:

Toggle	Middleware	Guidance
include_planning	TodoListMiddleware (write_todos)	Keep on only for multi-step actors
include_subagents	sub-agent fan-out (the task tool)	Highest token cost — enable only if delegation is needed
include_reflection	SummarizationMiddleware	Cheapest of the three, still adds a pass on long contexts

Two deepagents extras: extra_middleware appends your own module.path:ClassName middleware to the stack, and include_lean_channel routes one metadata channel (default voice) to a lean plain-tool agent for latency-critical surfaces.

Integrations, mesh, and toggles

integration_type selects the plugin slot under src/integrations/:

• none (default) — domain tools + MCP only.
• n8n — n8n REST client, /n8n proxy, and workflow-as-tool discovery for workflows tagged n8n_workflow_tag (default kaoohi-tool). n8n_allow_workflow_authoring defaults to false and is a security control, not a convenience — workflows can run arbitrary code on the deploying team’s instance.
• custom — a hand-authored integration in src/integrations/custom/.

Other shape decisions, all with safe defaults: fleet_mesh (inter-actor mesh client for suite actors), include_redis_reply_queue, include_scheduler, include_panel (owner-facing UI panel), include_actor_config_mixin (see ](en/track-a/config-and-verify/)), docker_workers (1/2/4), and resource_profile (auto derives from your answers at render time).

Marketplace metadata

The kaoohi_* variables feed the config emitter and end up in your actor’s marketplace card: kaoohi_category (deep_agent / productivity / communication / business / data), kaoohi_icon, kaoohi_image_repo (defaults to ghcr.io/allcare/<name> with underscores hyphenated), kaoohi_required_connectors / kaoohi_optional_connectors, kaoohi_capabilities, and kaoohi_expose_external_api with its operations/protocols sub-options (on by default; each kompanion gets a public URL + API key through the platform edge).

Post-generation setup

Three commands before anything else:

cd /path/to/my-actor

# 1. Apply ruff's import-modernization fixes to the fresh render
ruff check --fix --unsafe-fixes src/

# 2. Install the package with dev extras
pip install -e ".[dev]"

# 3. Create your env file
cp .env.example .env

In .env, set at minimum: KOMPANION_ID, TEAM_ID, COLLECTION_ID (any UUIDs for local dev), POSTGRES_URL / POSTGRES_PASSWORD, REDIS_URL, one LLM key (OPENAI_API_KEY or ANTHROPIC_API_KEY), and AUTH_API_URL / AUTH_API_KEY (any placeholder — authorization is off in dev).

Then verify the render:

pytest

The generated suite — health, config, settings, models, and the platform contract tests — should be green with zero domain code written. If it is not, the template version and your toolchain disagree; fix that before building domain logic.

Next: ](en/track-a/extension-points/), where the real work happens.

For kaboum’s own deep-dive on this flow, see its user guide, Part 2.